@ng-native/router 0.0.1 → 0.1.0

package/dist/native-stack-outlet.js

@@ -0,0 +1,564 @@
+/**
+ * A `RouterOutlet` that renders a native stack instead of swapping one view for another.
+ *
+ * The outlet's host element *is* the `RNSScreenStack`, and each activated route's component is
+ * created directly on its own `screen` child rather than on a wrapper view inside it (ADR 0004).
+ * The screens below the top stay mounted, which is what keeps a pushed-away screen's native
+ * state alive: its scroll offset, its text cursor, its keyboard focus.
+ *
+ * Push and pop are inferred from the calls the router already makes. With a reuse strategy that
+ * detaches, navigating forward is `detach()` then `activateWith()`, and navigating back is
+ * `detach()` then `attach(ref)` with a ref we handed out earlier. Finding that ref in our own
+ * stack is what identifies a pop, so nothing here needs to consult the URL.
+ *
+ * Note `activityState` is set once, to active, and never lowered. `Screen.tsx` throws on any
+ * decrease while `isNativeStack`, because a native stack decides what is visible from the order
+ * of its children rather than from a per-screen flag. Toggling that flag is for `ScreenContainer`
+ * (tabs), where every screen is mounted at once.
+ */
+import { ApplicationRef, ChangeDetectionStrategy, Component, DestroyRef, ElementRef, ErrorHandler, HostAttributeToken, Injector, Renderer2, computed, createComponent, inject, signal, } from '@angular/core';
+import { ActivatedRoute, ChildrenOutletContexts, NavigationCancel, NavigationEnd, NavigationError, PRIMARY_OUTLET, Router, createUrlTreeFromSnapshot, } from '@angular/router';
+import { Location, PlatformLocation } from '@angular/common';
+import { SCREEN_IN_FRONT } from '@ng-native/device';
+import { bindRouteInputs } from "./bind-route-inputs.js";
+import { NativeBack, isShowing } from "./native-back.js";
+import { intentOf } from "./native-navigation.js";
+import { NativePlatformLocation } from "./native-platform-location.js";
+import { markScreenRoute } from "./tab-routes.js";
+import { ownHost } from "./own-host.js";
+import { ActivityState } from "./screens.js";
+import * as i0 from "@angular/core";
+/**
+ * The last navigation, per router, whose presentation an outlet has already given a screen.
+ *
+ * Presenting a route that is a stack of its own activates two outlets in one navigation: the one
+ * the route is presented in, and the one inside it that shows the route's first child. Only the
+ * first is presented; the second is the first screen of a stack inside a presented screen, and a
+ * push inside that stack must see it as a pushed screen, not one to present over.
+ */
+const presented = new WeakMap();
+/** What every screen needs to fill the stack, the same five keys RNSScreen itself expects. */
+const FILL = { position: 'absolute', left: 0, right: 0, top: 0, bottom: 0 };
+export class NativeStackOutlet {
+    /**
+     * Named outlets work exactly as on the web: `<native-stack-outlet name="list" />` is filled by
+     * routes with `outlet: 'list'`. The default is the primary one. Read once, as the router's own
+     * outlet reads it, since an outlet cannot change which contexts it is registered under.
+     */
+    name = inject(new HostAttributeToken('name'), { optional: true }) ?? PRIMARY_OUTLET;
+    supportsBindingToComponentInputs = true;
+    parentContexts = inject(ChildrenOutletContexts);
+    renderer = inject(Renderer2);
+    applicationRef = inject(ApplicationRef);
+    injector = inject(Injector);
+    host = inject(ElementRef);
+    location = inject(Location);
+    history = inject(PlatformLocation);
+    /**
+     * Only for the intent a navigation carries. Optional so the outlet can be exercised through
+     * `RouterOutletContract` directly, which is how its own tests drive it.
+     */
+    router = inject(Router, { optional: true });
+    errors = inject(ErrorHandler);
+    entries = [];
+    /**
+     * The screens a replace or a reset supersedes, kept until the navigation that supersedes them
+     * succeeds: one that fails leaves the stack as it was.
+     */
+    superseded = null;
+    fill = { flex: 1 };
+    constructor() {
+        ownHost(this.host.nativeElement);
+        // Ours, not a prop of the native stack.
+        delete this.host.nativeElement.props['name'];
+        this.parentContexts.onChildOutletCreated(this.name, this);
+        // Android's back button, and `NativeNavigation.back()`. Declining at the bottom of the stack
+        // is deliberate: the outlet this one sits in gets its turn, and when none takes it the
+        // platform backgrounds the app, which is what a user expects, rather than the app swallowing
+        // the press and appearing stuck.
+        //
+        // Not yet verified on a device: whether react-native-screens' own Android back handling
+        // (`nativeBackButtonDismissalEnabled`) also pops the screen, which would make one press pop
+        // twice. If a back press ever skips a screen on Android, look here first.
+        const back = inject(NativeBack);
+        const unsubscribeBack = back.handle(() => this.goBack());
+        const unsubscribeStack = back.addStack({
+            showing: () => this.isShowing(),
+            popToRoot: () => (this.entries.length > 1 ? this.popToEntry(0) : null),
+            popTo: (url) => {
+                const index = this.entries.findIndex((entry) => this.urlOf(entry) === url);
+                return index !== -1 && index < this.entries.length - 1 ? this.popToEntry(index) : null;
+            },
+        });
+        // Optional for the same reason as the router: the outlet's own tests stand one in without it.
+        const navigations = this.router?.events?.subscribe((event) => {
+            if (event instanceof NavigationEnd)
+                this.settle(event.id);
+            else if (event instanceof NavigationError)
+                this.rollBack(event.id);
+        });
+        inject(DestroyRef).onDestroy(() => {
+            unsubscribeBack();
+            unsubscribeStack();
+            navigations?.unsubscribe();
+            for (const entry of this.entries) {
+                entry.unbind();
+                entry.ref.destroy();
+            }
+            this.entries.length = 0;
+            this.parentContexts.onChildOutletDestroyed(this.name);
+        });
+    }
+    /** The screens currently in the stack, oldest first. Exposed for tests. */
+    get depth() {
+        return this.entries.length;
+    }
+    // --- RouterOutletContract ----------------------------------------------
+    get isActivated() {
+        return this.top !== undefined && !this.top.detached;
+    }
+    get component() {
+        return this.top && !this.top.detached ? this.top.ref.instance : null;
+    }
+    get activatedRoute() {
+        return this.top && !this.top.detached ? this.top.route : null;
+    }
+    get activatedRouteData() {
+        return this.activatedRoute?.snapshot.data ?? {};
+    }
+    /** The input binder reads this to bind route params to component inputs. */
+    get activatedComponentRef() {
+        return this.top?.ref ?? null;
+    }
+    activateWith(route, environmentInjector) {
+        const component = (route.component ?? route.snapshot.component);
+        if (!component) {
+            throw new Error('[angular-native] route has no component to activate');
+        }
+        // Whatever a stack shows is a screen, children or not, and must survive being covered.
+        if (route.snapshot.routeConfig)
+            markScreenRoute(route.snapshot.routeConfig);
+        // What kind of navigation this is, over and above which route it lands on: a replace
+        // supersedes the screen below rather than stacking on it, and a reset empties the stack.
+        // Everything else leaves the screens below mounted, so their native state survives the trip.
+        const intent = this.currentIntent();
+        const navigation = this.navigationId();
+        const presentation = this.presentationFor(intent);
+        //
+        // The screen is the page's host element, so its props are set before the component exists
+        // and the component's own host bindings land on top of them. Style bindings merge key by
+        // key, so a page styling itself keeps the absolute fill the stack lays out with - except for
+        // `position` and the four insets, which a page naming them writes over outright rather than
+        // merging into. Those five are re-asserted below, after the page's own change detection has
+        // run, so the outlet's positioning always wins whatever a page's host style says.
+        const screen = this.createScreen(presentation);
+        const inFront = signal(true, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "inFront" }] : /* istanbul ignore next */ []));
+        const { ref, unbind } = this.createPage(component, route, environmentInjector, screen, inFront);
+        // The page's own host style, including any `position` or inset it declared, has now landed
+        // on the screen: put the stack's fill back over it. Per-key, through `setStyle`, so whatever
+        // else the page's style set - a background colour, say - still merges and stays.
+        this.fillScreen(screen);
+        if (intent?.stack === 'reset')
+            this.supersede(this.entries.slice(), navigation);
+        else if (intent?.stack === 'replace' && this.top)
+            this.supersede([this.top], navigation);
+        this.entries.push({
+            route,
+            ref,
+            screen,
+            detached: false,
+            unbind,
+            presentation,
+            activatedIn: navigation,
+            inFront,
+        });
+    }
+    /**
+     * The page's component, created on its screen and rendered once.
+     *
+     * A page that throws on that first render fails the navigation, and nothing of it may stay: a
+     * half-made screen left on the stack is one the router does not know about, with a component
+     * still running on it. So its component is destroyed, its screen taken off the stack, the
+     * screen it was pushed from given back its change detection, and the error handed to the
+     * app's `ErrorHandler` before the router fails the navigation with it.
+     */
+    createPage(component, route, environmentInjector, screen, inFront) {
+        let ref;
+        let unbind;
+        try {
+            ref = createComponent(component, {
+                environmentInjector,
+                elementInjector: this.outletInjector(route, inFront),
+                hostElement: screen,
+            });
+            this.applicationRef.attachView(ref.hostView);
+            // Route params onto inputs before the first change detection, not after: a required input
+            // read in the template throws NG0950 if it is still unset when the page first renders.
+            unbind = this.bindInputs(ref, route);
+            // Before anything can commit. Creating the page's nodes dirties the tree, which schedules a
+            // commit of its own - and that commit would capture the page with its elements created and
+            // its bindings not yet applied. On iOS the props catch up a frame later and nobody sees it;
+            // on Android the flattening decision is made from the props a view is created with, so a
+            // content wrapper that arrives without its `collapsable: false` is flattened for good and
+            // its children end up parented to a scroll view that allows exactly one.
+            ref.changeDetectorRef.detectChanges();
+            return { ref, unbind };
+        }
+        catch (error) {
+            unbind?.();
+            ref?.destroy();
+            this.removeScreen(screen);
+            this.uncover();
+            this.errors.handleError(error);
+            throw error;
+        }
+    }
+    deactivate() {
+        const entry = this.entries.pop();
+        if (!entry)
+            return;
+        this.drop(entry);
+    }
+    /**
+     * Hand the live `ComponentRef` back to the router without destroying it. The screen stays
+     * mounted, so the component keeps running and its native views keep their state.
+     */
+    detach() {
+        const entry = this.top;
+        if (!entry)
+            throw new Error('[angular-native] outlet is not activated, nothing to detach');
+        entry.detached = true;
+        entry.detachedIn = this.navigationId();
+        entry.inFront.set(false);
+        // `ChangeDetectorRef.detach`, not `ApplicationRef.detachView`. The latter calls
+        // `renderDetachView` and pulls the view's nodes out of the tree, which is exactly what we
+        // are trying to avoid: the screen would vanish from the stack the moment we pushed past it.
+        // This stops change detection for an off-screen screen while leaving it mounted.
+        entry.ref.hostView.detach();
+        return entry.ref;
+    }
+    /**
+     * Re-attach a previously detached ref. If we still hold it, everything stacked above it is a
+     * screen the user has navigated back past, so those are destroyed: that is the pop.
+     */
+    attach(ref, route) {
+        const index = this.entries.findIndex((entry) => entry.ref === ref);
+        if (index === -1) {
+            // Not ours: the router is restoring a ref detached by a different outlet instance. Its
+            // host element is already a screen, complete with the `dismissed` listener that outlet
+            // registered, so it is re-parented rather than rebuilt.
+            const screen = ref.location.nativeElement;
+            this.renderer.appendChild(this.host.nativeElement, screen);
+            this.entries.push({
+                route,
+                ref,
+                screen,
+                detached: false,
+                unbind: this.bindInputs(ref, route),
+                // What it was given is its first outlet's; this one has no say over that screen's.
+                inFront: signal(true),
+            });
+            this.applicationRef.attachView(ref.hostView);
+        }
+        else {
+            for (const above of this.entries.splice(index + 1))
+                this.drop(above);
+            const entry = this.entries[index];
+            entry.detached = false;
+            entry.inFront.set(true);
+            entry.route = route;
+            // The route object is new even when the url is not, so the inputs follow the new one.
+            entry.unbind();
+            entry.unbind = this.bindInputs(ref, route);
+        }
+        // Resume change detection for the screen the user is coming back to.
+        ref.hostView.reattach();
+    }
+    // --- native stack -------------------------------------------------------
+    /**
+     * Route params onto the page's inputs, but only in an app that asked for it with
+     * `withComponentInputBinding()`, which is the only time Angular's own outlet binds them. Read
+     * per screen rather than once, for a test that stands the router in.
+     */
+    bindInputs(ref, route) {
+        return this.router?.componentInputBindingEnabled ? bindRouteInputs(ref, route) : () => { };
+    }
+    get top() {
+        return this.entries[this.entries.length - 1];
+    }
+    /**
+     * What the navigation asked for, if it asked for anything. Read here rather than remembered,
+     * because the router is mid-navigation for exactly as long as an activation takes.
+     */
+    currentIntent() {
+        return intentOf(this.router?.getCurrentNavigation()?.extras.state);
+    }
+    /**
+     * How the screen a navigation activates is put on screen.
+     *
+     * A push on top of a presented screen is presented the same way. `RNSScreenStack` pushes a push
+     * screen that follows a modal onto the navigation controller under the modal, so the router
+     * would be on the new route while the modal stayed in front, and the modal's own way out would
+     * first pop a screen nobody could see. A presentation the navigation names itself wins, and a
+     * reset starts a stack with nothing to follow. A presented screen that is a stack of its own is
+     * where a push to one of its children goes instead, inside it.
+     */
+    presentationFor(intent) {
+        const own = this.claimPresentation(intent);
+        const covering = this.top?.presentation?.stackPresentation;
+        if (intent?.stack === 'reset' || !covering || covering === 'push' || own?.stackPresentation) {
+            return own;
+        }
+        return { ...own, stackPresentation: covering };
+    }
+    /** The navigation's own presentation, unless an outlet further out already presented it. */
+    claimPresentation(intent) {
+        if (!intent?.presentation)
+            return undefined;
+        const id = this.router?.getCurrentNavigation()?.id;
+        if (id === undefined)
+            return intent.presentation;
+        if (presented.get(this.router) === id)
+            return undefined;
+        presented.set(this.router, id);
+        return intent.presentation;
+    }
+    /** Take a screen out for good: its bindings, its component, and its native view. */
+    drop(entry) {
+        entry.unbind();
+        entry.ref.destroy();
+        this.removeScreen(entry.screen);
+    }
+    /** Take one entry out of the stack, wherever it is, and drop it. */
+    remove(entry) {
+        const index = this.entries.indexOf(entry);
+        if (index === -1)
+            return;
+        this.entries.splice(index, 1);
+        this.drop(entry);
+    }
+    // --- a navigation's outcome ----------------------------------------------
+    /** The id of the navigation in progress, when there is a router to say. */
+    navigationId() {
+        return this.router?.getCurrentNavigation()?.id;
+    }
+    /**
+     * Take out the screens a replace or a reset supersedes once its navigation has succeeded, or
+     * at once when there is no navigation to wait for. A replaced screen has already been detached
+     * by the router, and with `replaceUrl` its history entry is gone too, so nothing will attach it
+     * again; the reuse strategy notices the ref is destroyed and drops its handle.
+     */
+    supersede(entries, navigation) {
+        if (navigation === undefined) {
+            for (const entry of entries)
+                this.remove(entry);
+            return;
+        }
+        this.superseded = { entries, navigation };
+    }
+    /** A navigation succeeded: what it superseded goes, and what it did is no longer undoable. */
+    settle(navigation) {
+        if (this.superseded?.navigation === navigation) {
+            for (const entry of this.superseded.entries)
+                this.remove(entry);
+            this.superseded = null;
+        }
+        for (const entry of this.entries) {
+            if (entry.activatedIn === navigation)
+                entry.activatedIn = undefined;
+            if (entry.detachedIn === navigation)
+                entry.detachedIn = undefined;
+        }
+    }
+    /**
+     * A navigation failed, so the router is back where it started: undo what it did here too.
+     *
+     * The screen that threw has already gone (`createPage`), but a screen this outlet activated for
+     * the same navigation has not when the one that threw is further in, the first screen of a
+     * stack inside it. That one goes, with everything in it, and the screen it covered carries on.
+     */
+    rollBack(navigation) {
+        if (this.superseded?.navigation === navigation)
+            this.superseded = null;
+        for (const entry of this.entries.filter((candidate) => candidate.activatedIn === navigation)) {
+            this.remove(entry);
+        }
+        this.uncover(navigation);
+    }
+    /**
+     * Give the top screen back its change detection when the router covered it for a navigation
+     * that is not going to happen: the one given, or the one in progress.
+     */
+    uncover(navigation = this.navigationId()) {
+        const top = this.top;
+        if (!top?.detached || top.detachedIn !== navigation)
+            return;
+        top.detached = false;
+        top.detachedIn = undefined;
+        top.inFront.set(true);
+        top.ref.hostView.reattach();
+    }
+    /**
+     * `position: absolute` and the four insets, through `setStyle` rather than one `setProperty`
+     * so each key merges into whatever style is already on the screen instead of replacing it -
+     * the same merge a page's own host style gets, just asserted last so the stack's layout wins.
+     */
+    fillScreen(screen) {
+        for (const [key, value] of Object.entries(FILL)) {
+            this.renderer.setStyle(screen, key, value);
+        }
+    }
+    createScreen(presentation) {
+        const screen = ownHost(this.renderer.createElement('screen'));
+        this.fillScreen(screen);
+        // Set once and never lowered: see the note at the top of this file.
+        this.renderer.setProperty(screen, 'activityState', ActivityState.Active);
+        // A swipe-back or an Android back button pops the screen natively and only then tells JS.
+        // Without this the native stack and the router disagree from that moment on: the screen is
+        // gone but the URL still points at it, so the next navigation starts from the wrong place.
+        this.renderer.listen(screen, 'dismissed', (event) => this.onNativeDismiss(event?.nativeEvent?.dismissCount ?? 1));
+        // Every key is a prop `RNSScreen` already declares, spelled the way the codegen spec spells
+        // it, so this forwards rather than translates. Set before the screen joins the stack: the
+        // native side reads the presentation as it mounts.
+        for (const [prop, value] of Object.entries(presentation ?? {})) {
+            if (value !== undefined)
+                this.renderer.setProperty(screen, prop, value);
+        }
+        this.renderer.appendChild(this.host.nativeElement, screen);
+        return screen;
+    }
+    /**
+     * Follow a pop the user already made. `historyGo`, not `back()`, because iOS coalesces a long
+     * swipe into a single event with a count.
+     *
+     * Only ever fires for a native dismissal: verified on device that a pop this outlet drives
+     * itself emits `willAppear`/`appear` for the screen below but no `dismissed`, so there is no
+     * double-pop to guard against.
+     *
+     * The gesture itself is unverified by tooling: idb cannot synthesise a `UIScreenEdgePan` that
+     * UIKit accepts, so this path was reasoned from the events rather than driven end to end.
+     */
+    onNativeDismiss(count) {
+        this.popBy(Math.max(1, count));
+    }
+    /**
+     * A back, from the button or `NativeNavigation`: pop the top screen, as long as there is one
+     * below it and this stack is the one the user is looking at. A stack in a tab behind, or under
+     * a screen pushed over the tab bar, is still subscribed, and the newest one would otherwise
+     * answer for the stack in front.
+     */
+    goBack() {
+        if (this.entries.length < 2 || !this.isShowing())
+            return false;
+        this.popBy(1);
+        return true;
+    }
+    /** Whether the top screen is part of what the router shows now. Assumed without a router. */
+    isShowing() {
+        if (!this.router)
+            return true;
+        return this.isActivated && isShowing(this.router, this.top.route);
+    }
+    /**
+     * Take the router to the screen `steps` below the top, whether native already popped it or it
+     * is about to be popped because the router arrives there.
+     */
+    popBy(steps) {
+        const below = this.entries[this.entries.length - 1 - steps];
+        const url = below && this.router ? this.urlOf(below) : null;
+        // Usually the entry that far back is the screen the pop revealed, and going back through
+        // history keeps it tidy. Not always: a stack inside a tab shares history with the other tabs,
+        // so after a trip to one and back the entry behind the top screen is that other tab, and
+        // going back would switch tab rather than pop. Then the router is sent to the revealed
+        // screen instead, replacing the entry of the one that is gone.
+        const behind = this.historyUrl(-steps);
+        if (!url || behind === undefined || behind === url) {
+            this.location.historyGo(-steps);
+            return;
+        }
+        void this.router.navigateByUrl(url, { replaceUrl: true });
+    }
+    /**
+     * Take the router down to the screen at `index`, popping every screen above it together.
+     * Through history when the entries behind are these screens, so going back from there keeps
+     * working one screen at a time; otherwise by a navigation to it that replaces the entry, as
+     * `popBy` does when a tab's history interleaves.
+     */
+    popToEntry(index) {
+        const url = this.urlOf(this.entries[index]);
+        const steps = this.entries.length - 1 - index;
+        if (this.historyUrl(-steps) === url) {
+            const arrived = this.nextNavigation();
+            this.location.historyGo(-steps);
+            return arrived;
+        }
+        return this.router.navigateByUrl(url, { replaceUrl: true });
+    }
+    /** Whether the navigation that happens next succeeds. */
+    nextNavigation() {
+        return new Promise((resolve) => {
+            const events = this.router.events.subscribe((event) => {
+                if (event instanceof NavigationEnd)
+                    resolve(true);
+                else if (event instanceof NavigationError || event instanceof NavigationCancel) {
+                    resolve(false);
+                }
+                else
+                    return;
+                events.unsubscribe();
+            });
+        });
+    }
+    /** The url a screen was showing when it was covered, rebuilt from its own route snapshot. */
+    urlOf(entry) {
+        const snapshot = entry.route.snapshot;
+        const tree = createUrlTreeFromSnapshot(snapshot, [], snapshot.queryParams, snapshot.fragment);
+        return this.router.serializeUrl(tree);
+    }
+    /**
+     * The url of the history entry `offset` away, normalised the way the router writes it: null past
+     * the start of history, and undefined when the history is not ours to read, so the pop has to go
+     * through it blind.
+     */
+    historyUrl(offset) {
+        if (!(this.history instanceof NativePlatformLocation))
+            return undefined;
+        const url = this.history.ɵurlAt(offset);
+        return url === null ? null : this.router.serializeUrl(this.router.parseUrl(url));
+    }
+    removeScreen(screen) {
+        this.renderer.removeChild(this.host.nativeElement, screen);
+    }
+    /**
+     * What a page is created with: its route, the outlet contexts its own outlets register in, and
+     * whether its screen is in front - which is this screen's own say and, for a stack inside a
+     * screen of another, that screen's too.
+     */
+    outletInjector(route, inFront) {
+        const outer = this.injector.get(SCREEN_IN_FRONT);
+        return Injector.create({
+            parent: this.injector,
+            providers: [
+                { provide: SCREEN_IN_FRONT, useValue: computed(() => outer() && inFront()) },
+                { provide: ActivatedRoute, useValue: route },
+                {
+                    provide: ChildrenOutletContexts,
+                    useValue: this.parentContexts.getOrCreateContext(this.name).children,
+                },
+            ],
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.0", ngImport: i0, type: NativeStackOutlet, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.2.0", type: NativeStackOutlet, isStandalone: true, selector: "native-stack-outlet", host: { properties: { "style": "fill" } }, ngImport: i0, template: '', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.0", ngImport: i0, type: NativeStackOutlet, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'native-stack-outlet',
+                    template: '',
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    host: { '[style]': 'fill' },
+                }]
+        }], ctorParameters: () => [] });
+//# sourceMappingURL=native-stack-outlet.js.map