@bitforgehq/ui 0.3.0

package/ai/components/stack-outlet.md

@@ -0,0 +1,661 @@
+# bf-stack-outlet
+
+Router outlet keeping a live page stack with slide transitions and iOS swipe back
+
+`BfStackOutletComponent` from `@bitforgehq/ui/mobile` · Navigation · since 0.2.0
+
+## Example
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfNavController,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+
+/** `bf-stack-outlet` showcase root: pushes a two-level flow that pops with the back button or a swipe. */
+@Component({
+  selector: 'app-stack-outlet-showcase',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfListComponent,
+    BfListItemComponent,
+  ],
+  template: `
+    <bf-page data-showcase="stack-outlet">
+      <bf-header title="Stack outlet" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            Push two pages, then pop them with the back button or, in iPhone mode, by dragging from
+            the left edge.
+          </p>
+          <bf-list [inset]="false">
+            <bf-list-item
+              title="Level 1"
+              [interactive]="true"
+              [chevron]="true"
+              (clicked)="push()"
+            />
+          </bf-list>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class StackOutletShowcasePage {
+  private readonly nav = inject(BfNavController);
+
+  push(): void {
+    void this.nav.forward('/showcase/stack-outlet/1');
+  }
+}
+```
+
+## Overview
+
+A router outlet that keeps a stack of live pages: a push slides the new page in and parks the
+previous one (still in the DOM, so scroll and state survive), a pop slides the top page out and
+destroys it, and on iOS a finger's edge swipe scrubs the pop (touch only: a mouse or pen drag
+never arms it). `provideBfShell({ maxLivePages })` bounds the live pages of each stack: the
+deepest ones are destroyed and created again, scroll restored, on a pop back to them. Replaces
+`<router-outlet>` in a mobile app.
+Pages receive route params, query params and route data as inputs, bound by the outlet itself.
+Inside `bf-tabs` it keeps one stack per tab and switches between them without a transition.
+Outlets nest: an outlet inside a page (the tabs page) keeps its stacks while an outer outlet
+parks that page, and `BfNavController` follows the innermost outlet whose page is shown.
+
+The router outlet of a mobile app. A plain `<router-outlet>` destroys the page you leave, so going
+back rebuilds it: the list is scrolled to the top again, loaded data is fetched again, and there is
+nothing left to slide back to. `bf-stack-outlet` keeps a stack of live pages instead. A push slides
+the new page in over the current one, which stays in the DOM (hidden and inert) with its scroll
+position and state. A pop slides the top page out, destroys it and shows the page below exactly as
+it was. On iOS the pop can be scrubbed with a swipe from the left edge, like a native navigation
+controller. The stack follows the browser history, so the Android back button, `Location.back()`
+and the browser's own back button all pop.
+
+## When to use
+
+Use `bf-stack-outlet` in place of `router-outlet` in the Capacitor shell, so pushed pages stay alive and slide like native navigation. Use [bf-tabs](https://bitforge-ui.web.app/components/tabs) instead for one stack per tab, and a plain `router-outlet` on a desktop web app.
+
+## Setup
+
+Replace `<router-outlet>` with `<bf-stack-outlet />` and add the shell providers. `provideBfShell()`
+provides the configuration and the stack's route reuse strategy (`BfStackReuseStrategy`: a change of
+path params such as `/items/4 → /items/5` is a new page), and starts the platform services.
+`BfNavController` and the overlay services (`BfSheetService`, `BfModalService`, `BfToastService`,
+`BfActionSheetService`, `BfAlertDialogService`) are provided in root and tree-shakable: an app
+that never injects an overlay service bundles no overlay code. Put `provideBfShell()` in the
+application providers; in a lazy route's `providers` the services still come from the root
+injector.
+`withBfShellRouting()` sets `canceledNavigationResolution: 'computed'`, so a back navigation that a
+guard refuses restores the history position and the stack stays in sync with it.
+The stack outlet binds route state to its pages' inputs itself; keep `withComponentInputBinding()`
+so nested `<router-outlet>`s inside pages bind the same way.
+
+```ts
+import { type ApplicationConfig, Component } from '@angular/core';
+import { type Routes, provideRouter, withComponentInputBinding } from '@angular/router';
+import { BfStackOutletComponent, provideBfShell, withBfShellRouting } from '@bitforgehq/ui/mobile';
+
+/** The app's routes; every navigation to a new page pushes it onto the stack. */
+export const routes: Routes = [];
+
+/** The shell providers next to the router. */
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes, withComponentInputBinding(), withBfShellRouting()),
+    provideBfShell({ mode: 'auto', swipeBack: true, deferTransitionStart: true }),
+  ],
+};
+
+/**
+ * The shell setup: the providers, and the stack outlet in place of router-outlet.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-stack-outlet-setup',
+  imports: [BfStackOutletComponent],
+  template: `<bf-stack-outlet />`,
+})
+export class StackOutletSetupExampleComponent {}
+```
+
+Navigate with `routerLink` or the router as usual; every navigation to a new page pushes. Use
+`BfNavController` for explicit directions: `forward(url)` pushes, `back()` pops through the real
+history and `root(url)` replaces the whole stack. `nav.canGoBack()` and `nav.depth()` follow the
+deepest outlet whose page is shown (see Nested outlets).
+
+## Pages read route state through inputs
+
+A parked page keeps the `ActivatedRoute` it was created with, and after a pop the router hands the
+outlet a new one: the observables of the injected route no longer emit. Take route params, query
+params and route data (including resolved data) through inputs instead. The outlet binds them
+itself, with or without `withComponentInputBinding()`, and re-binds them to the new route after a
+pop. It binds like the router's default: query params, then path params, then data, and an input
+with no matching key is set to `undefined`. It does not read the options of
+`withComponentInputBinding()` (`queryParams: false`, `unmatchedInputBehavior`) and does not bind
+the experimental route `resources`.
+
+```ts
+import { Component, input } from '@angular/core';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A page that reads its route param as an input.
+ *
+ * The `tasks/:id` route's `id` param arrives as the page's `id` input, including when the stack
+ * re-shows the page.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-stack-outlet-inputs',
+  imports: [BfContentComponent, BfHeaderComponent, BfPageComponent],
+  template: `
+    <bf-page>
+      <bf-header [title]="'Task ' + id()" [largeTitle]="false" />
+      <bf-content>
+        <p class="p-4">Details of task {{ id() }}.</p>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class StackOutletInputsExampleComponent {
+  /** From the `tasks/:id` route param. */
+  readonly id = input.required<string>();
+}
+```
+
+## Nested child routes
+
+Child routes rendered by a `<router-outlet>` inside a page (tabs inside a detail page, for
+example) do not push: switching between `/items/4` and `/items/4/notes` changes the child, not the
+stack. Popping back to such a page lands on the child it last showed. Popping the page itself —
+the back button, the swipe or `nav.back()` — goes back past the entries its child navigations
+(and query-only changes) added, in one history step, to the entry before the page was pushed.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterOutlet } from '@angular/router';
+import { BfContentComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A page with child routes of its own.
+ *
+ * The child routes render in a plain `router-outlet` inside the page: switching between them
+ * does not push a new page.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-stack-outlet-child-routes',
+  imports: [BfContentComponent, BfPageComponent, RouterLink, RouterOutlet],
+  template: `
+    <bf-page>
+      <bf-content>
+        <nav class="flex gap-4 p-4">
+          <a routerLink="./">Overview</a>
+          <a routerLink="notes">Notes</a>
+        </nav>
+        <router-outlet />
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class StackOutletChildRoutesExampleComponent {}
+```
+
+## Swipe-back and horizontal scrollers
+
+In iOS mode a finger drag that starts within 50 px of the left edge scrubs the pop; releasing it
+with a flick or past half the width completes it, anything else slides the page back. Only touch
+arms it (`pointerType` `touch`): a mouse drag or a text selection from the edge, and a pen, never
+pop the page, also on a desktop web page with the mode forced to `ios`. Turn the gesture off for
+one outlet with `[swipeGesture]="false"`, or for the app with `provideBfShell({ swipeBack: false })`.
+
+A horizontal scroller inside a page (a chips row, a carousel) needs nothing: `overflow-x-auto`
+makes it a scroll container, and `touch-action` is intersected only up to a touch's nearest scroll
+container (it is not inherited), so the outlet host's `touch-action: pan-y` never reaches it and
+the row pans on its own. The host's value only keeps horizontal drags as pointer events where the
+host itself is the nearest scroll container (the header), for the swipe-back. A drag that starts
+in the 50 px edge zone is the swipe-back even on a scroller; anywhere else the scroller keeps its
+own scrolling. `bfHorizontalScroll` is deprecated for that reason.
+
+```ts
+import { Component } from '@angular/core';
+import { BfChipComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A stacked page with a horizontal chips row.
+ *
+ * The row scrolls sideways under a finger with `overflow-x-auto` alone; only a drag that starts in
+ * the 50 px left edge is the swipe-back.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-stack-outlet-scroller',
+  imports: [BfChipComponent, BfContentComponent, BfHeaderComponent, BfPageComponent],
+  template: `
+    <bf-page>
+      <bf-header title="Tasks" />
+      <bf-content>
+        <div class="flex gap-2 overflow-x-auto px-4 py-2">
+          @for (filter of filters; track filter) {
+            <bf-chip class="shrink-0">{{ filter }}</bf-chip>
+          }
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class StackOutletScrollerExampleComponent {
+  protected readonly filters = ['All', 'Open', 'Done', 'Mine', 'Starred', 'Archived'];
+}
+```
+
+## Bounded stacks
+
+Every pushed page stays alive until it is popped, so a long flow (a folder tree, a feed that
+pushes page after page) keeps every page in memory. `provideBfShell({ maxLivePages: n })` bounds
+it: when a stack holds more than `n` pages, the outlet destroys the components of the deepest
+ones and keeps only a record of each (its route, URL, history position and the `bf-content`
+scroll position). The top `n` pages stay alive. A pop back to such a page creates it again from
+the route the router re-activates, in a new frame, restores its scroll after the first render and
+runs the usual pop transition and lifecycle (`bfViewWillEnter`, `bfViewDidEnter`). The default
+is `Infinity`: every page stays alive, as before.
+
+Deep pages come back fresh: whatever lived only in the destroyed component (a form's typed text,
+a local signal, loaded data kept in the page) is gone, and the stacks of outlets nested inside it
+start over at their first page. Keep such state in a service, or keep `maxLivePages` above the
+depth your flows reach. With `maxLivePages: 1` the page under the top one is always a record, so
+the edge swipe-back does not arm (there is nothing to show under the finger); the back button and
+`nav.back()` still pop.
+
+```ts
+import { type ApplicationConfig, Component } from '@angular/core';
+import { type Routes, provideRouter, withComponentInputBinding } from '@angular/router';
+import { BfStackOutletComponent, provideBfShell, withBfShellRouting } from '@bitforgehq/ui/mobile';
+
+/** The app's routes, including a flow that can push many pages (a folder tree, a feed). */
+export const routes: Routes = [];
+
+/** At most 10 pages of each stack stay alive; deeper ones come back fresh on a pop. */
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes, withComponentInputBinding(), withBfShellRouting()),
+    provideBfShell({ maxLivePages: 10 }),
+  ],
+};
+
+/**
+ * A stack that bounds its memory.
+ *
+ * With `maxLivePages`, the outlet destroys the deepest pages beyond the limit and creates them
+ * again, scrolled where they were, when the user pops back to them.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-stack-outlet-bounded',
+  imports: [BfStackOutletComponent],
+  template: `<bf-stack-outlet />`,
+})
+export class StackOutletBoundedExampleComponent {}
+```
+
+## Material mode
+
+`mode: 'md'` (and `mode: 'auto'` on Android and the web) replaces the slide with Material's
+220 ms fade-up: the new page fades in while rising 16 px, a pop is the reverse. There is no
+parallax, no dim layer and no edge gesture. `[animated]="false"` switches pages without any
+animation in either mode; the lifecycle events and `transitionStarted` / `transitionEnded` still fire.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfStackChange, BfStackOutletComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * An outlet without transitions that reports its depth.
+ *
+ * `[animated]="false"` swaps pages without the push animation; `stackChanged` reports the depth.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-stack-outlet-material',
+  imports: [BfStackOutletComponent],
+  template: `<bf-stack-outlet [animated]="false" (stackChanged)="onChange($event)" />`,
+})
+export class StackOutletMaterialExampleComponent {
+  protected readonly depth = signal(1);
+
+  protected onChange(change: BfStackChange): void {
+    this.depth.set(change.depth);
+  }
+}
+```
+
+## One stack per tab
+
+Inside `bf-tabs` the outlet keeps one stack per tab, keyed by the URL segment after the tabs route
+(`BF_TAB_CONTEXT`). A navigation onto another tab's segment parks the whole current stack and shows
+the other tab's stack — its page for that URL, with any pages above it dropped — or starts it with a
+new page. A switch has no transition and no swipe-back; `stackChanged` reports the active stack's
+`depth` with its `tabKey`, `BfNavController.depth` follows the active stack and pops stay within it.
+`lastUrlOf(tabKey)` returns the URL of a tab's top page (where `bf-tabs` navigates on a tab switch)
+, `popToRoot()` goes back in history to the active stack's first page in one step (false when that
+position is unknown), and `scrollActiveContentToTop()` scrolls the active page's `bf-content` to
+the top.
+
+## Nested outlets
+
+A page can host a `bf-stack-outlet` of its own: the usual case is a root outlet whose `tabs` page
+holds the outlet inside `bf-tabs`, next to root-level pages such as `/gallery` or `/login`. The
+outlets share one `BfNavController`: `depth`, `canGoBack` and `back()` follow the **deepest active
+outlet**, the innermost one whose page is shown. While you move inside the tabs that is the tab's
+stack; once the root outlet pushes `/gallery` above the tabs page, it is the root outlet.
+
+Pushing above the tabs page parks it with its outlet and every tab stack intact. Popping back —
+the back button, the swipe, the browser's back or `nav.back()` — shows the tabs page exactly as it
+was left, including the detail page on top of the active tab. `nav.root('/login')` replaces the
+root stack, and the tabs page with all its stacks is destroyed. The Android back button pops the
+deepest active outlet, and only when every shown outlet is at its first page moves the app to the
+background (`provideBfShell({ backAtRoot: 'exit' })` finishes it instead). An edge
+swipe pops the innermost outlet that can pop. The pages inside a parked page get their lifecycle
+events too: the active tab page gets `bfViewWillLeave`/`bfViewDidLeave` when `/gallery` is pushed
+above the tabs page, and `bfViewWillEnter`/`bfViewDidEnter` when it comes back.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { type Routes } from '@angular/router';
+import { BfButtonComponent, BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfNavController,
+  BfPageComponent,
+  BfStackOutletComponent,
+  BfTabsComponent,
+} from '@bitforgehq/ui/mobile';
+import { Sun, User } from 'lucide';
+
+/** The Today tab's page. */
+@Component({
+  selector: 'app-today-page',
+  imports: [BfContentComponent, BfHeaderComponent, BfPageComponent],
+  template: `
+    <bf-page>
+      <bf-header title="Today" />
+      <bf-content><p class="p-4">Three tasks due.</p></bf-content>
+    </bf-page>
+  `,
+})
+export class TodayPage {}
+
+/** The Me tab's page: it pushes onto the root outlet, above the tabs page. */
+@Component({
+  selector: 'app-me-page',
+  imports: [BfButtonComponent, BfContentComponent, BfHeaderComponent, BfPageComponent],
+  template: `
+    <bf-page>
+      <bf-header title="Me" />
+      <bf-content>
+        <bf-button class="m-4" (clicked)="openGallery()">Open the gallery</bf-button>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class MePage {
+  private readonly nav = inject(BfNavController);
+
+  openGallery(): void {
+    void this.nav.forward('/gallery');
+  }
+}
+
+/** The tabs page: the outlet nested in `bf-tabs`, one stack per tab. */
+@Component({
+  selector: 'app-tabs-page',
+  imports: [
+    BfIconComponent,
+    BfStackOutletComponent,
+    BfTabBarComponent,
+    BfTabComponent,
+    BfTabsComponent,
+  ],
+  template: `
+    <bf-tabs tabsPath="tabs">
+      <bf-stack-outlet />
+      <bf-tab-bar>
+        <bf-tab id="today" label="Today"><bf-icon [icon]="sun" /></bf-tab>
+        <bf-tab id="me" label="Me"><bf-icon [icon]="user" /></bf-tab>
+      </bf-tab-bar>
+    </bf-tabs>
+  `,
+})
+export class TabsPage {
+  protected readonly sun = Sun;
+  protected readonly user = User;
+}
+
+/** The app's routes: the tabs page and a root-level gallery. */
+export const routes: Routes = [
+  {
+    path: 'tabs',
+    component: TabsPage,
+    children: [
+      { path: 'today', component: TodayPage },
+      { path: 'me', component: MePage },
+      { path: '', redirectTo: 'today', pathMatch: 'full' },
+    ],
+  },
+  // A root-level page, pushed above the tabs page; it loads in its own chunk.
+  { path: 'gallery', loadComponent: () => import('./gallery.page').then((m) => m.GalleryPage) },
+  { path: '', redirectTo: 'tabs', pathMatch: 'full' },
+];
+
+/**
+ * Nested outlets: a root outlet whose tabs page holds its own outlet.
+ *
+ * The app component holds the root outlet; the tabs page nests one inside `bf-tabs`, and the Me
+ * page pushes `/gallery` onto the root outlet, above the tabs page.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-stack-outlet-nested-outlets',
+  imports: [BfStackOutletComponent],
+  template: `<bf-stack-outlet />`,
+})
+export class StackOutletNestedOutletsExampleComponent {}
+```
+
+## Desktop
+
+`bf-stack-outlet` is part of the Capacitor shell (`provideBfShell()`). A desktop web app uses a plain `router-outlet`: pages replace each other and the browser keeps the history. Inside the shell, the browser's back and forward buttons and their shortcuts pop and push, because the stack follows the history. The edge swipe-back answers touch only, so a mouse drag or a text selection that starts at the left edge never pops a page.
+
+## Theming
+
+- Page frame: every page sits in a frame with the `bg` background, so a sliding page never shows
+  the page under it through transparent areas.
+- Dim layer: `scrim` (black in both modes) at 15 % (`bg-scrim/15`), faded in over the page under a push.
+- Edge shadow of the sliding page: `shadow-floating`.
+- The host is `display: block; height: 100%`; give its container a height (the app shell or
+  `h-dvh`).
+
+## Accessibility
+
+Only the top page is exposed: parked pages are `visibility: hidden`, `inert` and
+`aria-hidden="true"`, so neither the keyboard nor a screen reader can reach them, and their change
+detection is paused. The shown page's `bf-content` is the document's one `main` landmark
+(`role="main"`), so a screen reader's landmark jump lands on the page content. During a transition only the entering page is interactive. On push, focus
+moves to the entering page's title — the element marked `data-bf-page-title` (the `bf-header` title
+once it exists), made focusable with `tabindex="-1"` — or to the page frame when there is none. On
+pop, focus returns to the element that had it when the page was left (the row that was tapped),
+with `preventScroll` so the restored scroll position does not jump. Under
+`prefers-reduced-motion: reduce` push and pop become a 150 ms cross-fade with no movement.
+
+## Inputs
+
+| Name           | Type      | Default     | Description                                                                          |
+| -------------- | --------- | ----------- | ------------------------------------------------------------------------------------ |
+| `name`         | `string`  | `'primary'` | Outlet name, as on `router-outlet`.                                                  |
+| `swipeGesture` | `boolean` | `true`      | Enables the iOS edge swipe-back for this outlet (ignored in Material mode).          |
+| `animated`     | `boolean` | `true`      | Animates push and pop; false switches pages instantly (lifecycle events still fire). |
+
+## Outputs
+
+| Name                | Payload                  | Description                                                                                                                                         |
+| ------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stackChanged`      | `BfStackChange`          | Emitted with the new depth after every change of the stack.                                                                                         |
+| `transitionStarted` | `BfStackTransitionEvent` | Emitted when a transition between two pages starts (also the start of a swipe-back).                                                                |
+| `transitionEnded`   | `BfStackTransitionEvent` | Emitted when a transition between two pages has settled.                                                                                            |
+| `stackChange`       | `BfStackChange`          | Emitted with the new depth after every change of the stack, together with `stackChanged`. **Deprecated** (0.3.0 use stackChanged; removed in 0.4.0) |
+| `transitionStart`   | `BfStackTransitionEvent` | Emitted when a transition starts, together with `transitionStarted`. **Deprecated** (0.3.0 use transitionStarted; removed in 0.4.0)                 |
+| `transitionEnd`     | `BfStackTransitionEvent` | Emitted when a transition has settled, together with `transitionEnded`. **Deprecated** (0.3.0 use transitionEnded; removed in 0.4.0)                |
+
+## Methods
+
+### `lastUrlOf(tabKey: string): string | null`
+
+The URL of the top page of a tab's stack (inside `bf-tabs`), or null when that tab has no
+stack yet. `bf-tabs` navigates there on a tab switch, so the tab comes back as it was left.
+
+| Parameter | Type     | Description                                           |
+| --------- | -------- | ----------------------------------------------------- |
+| `tabKey`  | `string` | The key of the tab, the URL segment after `tabsPath`. |
+
+### `popToRoot(): boolean`
+
+Pops the active stack back to its first page in one history step (`Location.historyGo(-n)`
+to the entry before the second page was pushed), keeping that page alive. Returns false, and
+does nothing, when the stack has one page or the history position is unknown.
+
+### `scrollActiveContentToTop(behavior?: ScrollBehavior): void`
+
+Scrolls the active page's `bf-content` back to the top (a re-selected tab).
+
+| Parameter   | Type             | Description                          |
+| ----------- | ---------------- | ------------------------------------ |
+| `behavior?` | `ScrollBehavior` | `smooth` (the default) or `instant`. |
+
+## Notes
+
+### Do
+
+- Use one `bf-stack-outlet` per navigation stack, in place of `<router-outlet>`.
+- Take route params as inputs, and load data in `bfViewDidEnter` or from the inputs.
+- Put horizontal scrollers inside pages as plain `overflow-x-auto` rows; they pan on their own.
+- Set `maxLivePages` for flows that push without bound, and keep their state in services.
+
+### Don't
+
+- Don't `inject(ActivatedRoute)` in a routed page to read params; it goes stale after a pop.
+- Don't enable WKWebView's `allowsBackForwardNavigationGestures`; it competes with the edge swipe.
+- Don't navigate imperatively to a page that is already in the stack to go back to it; call
+  `nav.back()` (a new navigation always pushes).
+
+## Migration notes
+
+### 0.3.0
+
+**Deprecated:** `stackChange` → `stackChanged`, `transitionStart` → `transitionStarted` and
+`transitionEnd` → `transitionEnded`. The new outputs emit the same `BfStackChange` and
+`BfStackTransitionEvent` objects at the same moments; the old names still emit them right after
+until 0.4.0 (see Migration 23).
+
+JSDoc of `stack-outlet.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs; template handlers and framework hooks marked `@internal`, so the reference
+leaves them out. No behaviour change.
+
+Setup in `docs.md`: `provideBfShell()` provides the configuration and the reuse strategy and starts
+the platform services; `BfNavController` and the overlay services are root-provided and
+tree-shakable.
+
+The `router.events` subscription says in a comment why it stays: the stack pairs each navigation
+id's start with its own end. No behaviour change.
+
+**Behaviour:** the iOS edge swipe-back arms only for `pointerType` `touch`: a mouse drag or a
+text selection from the left edge, and a pen, never pop the page (a desktop web page with the mode
+forced to `ios`). See Migration 39.
+
+New `maxLivePages` (through `provideBfShell()`, default `Infinity`): above it, the outlet destroys
+the components of the deepest pages of a stack and keeps a record of each (route, key, history
+position, navigation id, URL and the `bf-content` scroll position); the top `maxLivePages` pages
+stay alive. A pop back to such a page creates it again from the re-activated route in a new frame,
+restores its scroll after the first render and runs the pop transition and lifecycle. Deep pages
+come back fresh: nested outlets inside a destroyed page lose their stacks. With `maxLivePages: 1`
+the swipe-back does not arm (the page below is a record). The deprecated `stackChange`,
+`transitionStart` and `transitionEnd` keep emitting after their replacements.
+
+The host's `touch-action: pan-y` comment and the docs follow the Pointer Events model: page
+scrollers, horizontal rows included, keep their own panning (see `### horizontal-scroll`).
+
+### 0.2.0
+
+New `bf-stack-outlet`: a router outlet that keeps a stack of live pages instead of destroying the
+one you leave, implementing `RouterOutletContract` in place of `<router-outlet>`. A push slides
+the new page in and parks the previous one (`visibility: hidden`, `inert`, `aria-hidden`, detached
+change detector, scroll and state kept); a pop slides the top page out, destroys it and restores
+the page below with focus returned (`preventScroll`) to whatever had it. Push vs. pop is
+classified from the router's navigation trigger and the history positions the router records
+(`computed` resolution), so `replaceUrl`, redirects, refused guards, `history.go(-n)` and browser
+forward resolve correctly. A pop always goes back to the history entry before the page was pushed,
+in one step, even when the page added entries of its own (query-only or nested child
+navigations); a swipe whose history step does not pop the outlet slides the page back. Transitions follow `BfShellConfig.mode`: iOS is a 500 ms
+slide-and-parallax under a dimming layer with an edge-swipe-back (50 px left edge, Pointer Events,
+scrubs the pop's `currentTime`, completes on velocity or half-width, `Location.back()` on
+completion); Material is a 220 ms fade-up with no gesture; `prefers-reduced-motion` reduces both to
+a 150 ms cross-fade. `stackChange`, `transitionStart` and `transitionEnd` outputs report depth and
+transition state. `BfNavController` (root, `providedIn: 'root'`) exposes `forward()`, `back()`,
+`root()`, `canGoBack` and `depth` (see `### nav controller`; `back()` pops the top page in one
+history step); `withBfShellRouting()` sets
+`canceledNavigationResolution: 'computed'` so a refused back navigation stays in sync with the
+outlet. The outlet binds route params, query params and route data to its pages' inputs itself
+(`bindInputs`), so a parked page's `ActivatedRoute` staying stale after a pop is never a problem.
+Every primary outlet registers with `BfNavController` on init (`registerOutlet(outlet, level)`,
+`level` = number of stack outlets around it) and unregisters on destroy; it no longer registers
+a hardware back handler of its own.
+
+Multi-stack: inside `bf-tabs` (optional `BF_TAB_CONTEXT`) the outlet keeps one stack per tab key
+(`Map<tabKey, StackEntry[]>`). A navigation onto another tab key is a `switch`: the whole current
+stack is parked (every page hidden, `inert`, change detection detached), and the target stack is
+restored — its page for the URL re-activated (attached, visible, focus to its title) with any
+pages above it dropped — or started with a new page; no transition and no gesture. A `root`
+navigation into another tab replaces only that tab's stack. `depth`/`canGoBack` reflect the active
+stack, pops stay within it, and `stackChange` now emits `{ depth, tabKey }` (`tabKey` null outside
+`bf-tabs`). New public methods `lastUrlOf(tabKey)` (URL of a tab's top page), `popToRoot()` (goes back in
+history to the active stack's first page in one step; false when its position is unknown) and
+`scrollActiveContentToTop(behavior?)` (through the active page's `BfPageContext` scroller, which
+the outermost `bf-page` now registers with the outlet).
+
+Nested outlets: an outlet inside a page of another outlet (the outlet in `bf-tabs` on a tabs page
+hosted by the root outlet) keeps its stacks while the outer outlet parks that page. Each page gets
+a per-page host token that tells the outlets inside it whether the page is shown; when the router
+deactivates the inner outlet because the outer one pushed a page above its host (e.g.
+`/tabs/today/task/1` → `/gallery`), the inner outlet suspends instead of destroying its stacks,
+and when the outer outlet pops back it resumes the same page (same DOM nodes, every tab stack
+intact) without a transition. A history step that lands on another page of the inner stack pops
+within it as usual. The page shown by the inner outlet follows its host page's lifecycle: it gets
+`willLeave`/`didLeave` when the host is parked and `willEnter`/`didEnter` when it comes back
+(forwarded only on a real state change, so no duplicate events). An edge swipe is claimed by the
+innermost outlet that can pop — also while that outlet is mid-transition, where the swipe is
+ignored — so nested outlets never pop together.
+
+Modal depth: the outlet's host now carries a scale rule keyed to `--bf-modal-depth` (written by
+`BfOverlayStack` on every registered outlet root while a page-sheet `bf-modal` is open — see
+`### modal`): `transform: scale(calc(1 - var(--bf-modal-depth, 0) * 0.08))
+translateY(calc(var(--bf-modal-depth, 0) * 8px))`, `border-radius: calc(var(--bf-modal-depth, 0) *
+12px)`, a 260 ms transition on both (skipped under `prefers-reduced-motion`), `transform-origin:
+top center`. At depth 0 the rule is a no-op; each stacked modal scales the page stack down another
+8 % and rounds its corners another 12 px.