@ionic/react-router 8.7.13-dev.11766070268.1ab3dde2 → 8.7.13-dev.11766090775.11e2bebb

package/dist/index.js

@@ -796,7 +796,6 @@ class ReactRouterViewStack extends ViewStacks {
                 });
                 if (hasSpecificMatch) {
                     viewItem.mount = false;
-                    // Also hide the ion-page element immediately to prevent visual overlap
                     if (viewItem.ionPageElement) {
                         viewItem.ionPageElement.classList.add('ion-page-hidden');
                         viewItem.ionPageElement.setAttribute('aria-hidden', 'true');
@@ -1191,18 +1190,12 @@ const VIEW_UNMOUNT_DELAY_MS = 250;
  */
 const ION_PAGE_WAIT_TIMEOUT_MS = 50;
 const isViewVisible = (el) => !el.classList.contains('ion-page-invisible') && !el.classList.contains('ion-page-hidden');
-/**
- * Hides an ion-page element by adding hidden class and aria attribute.
- */
 const hideIonPageElement = (element) => {
     if (element) {
         element.classList.add('ion-page-hidden');
         element.setAttribute('aria-hidden', 'true');
     }
 };
-/**
- * Shows an ion-page element by removing hidden class and aria attribute.
- */
 const showIonPageElement = (element) => {
     if (element) {
         element.classList.remove('ion-page-hidden');
@@ -1227,28 +1220,18 @@ class StackManager extends React.PureComponent {
         this.skipTransition = false;
     }
     /**
-     * Determines the parent path that was matched to reach this outlet.
-     * This helps with nested routing in React Router 6.
-     *
-     * The algorithm finds the shortest parent path where a route matches the remaining path.
+     * Determines the parent path for nested routing in React Router 6.
      * Priority: specific routes > wildcard routes > index routes (only at mount point)
      */
     getParentPath() {
         const currentPathname = this.props.routeInfo.pathname;
-        // If this outlet previously established a mount path and the current
-        // pathname is outside of that scope, do not attempt to re-compute a new
-        // parent path. This prevents out-of-scope outlets from "adopting"
-        // unrelated routes (e.g., matching their index route under /overlays).
+        // Prevent out-of-scope outlets from adopting unrelated routes
         if (this.outletMountPath && !currentPathname.startsWith(this.outletMountPath)) {
             return undefined;
         }
-        // Check if this outlet has route children to analyze
         if (this.ionRouterOutlet) {
             const routeChildren = extractRouteChildren(this.ionRouterOutlet.props.children);
             const { hasRelativeRoutes, hasIndexRoute, hasWildcardRoute } = analyzeRouteChildren(routeChildren);
-            // Root outlets have IDs like 'routerOutlet' or 'routerOutlet-2'
-            // But even outlets with auto-generated IDs may need parent path computation
-            // if they have relative routes (indicating they're nested outlets)
             const isRootOutlet = this.id.startsWith('routerOutlet');
             const needsParentPath = !isRootOutlet || hasRelativeRoutes || hasIndexRoute;
             if (needsParentPath) {
@@ -1260,7 +1243,6 @@ class StackManager extends React.PureComponent {
                     hasIndexRoute,
                     hasWildcardRoute,
                 });
-                // Update the outlet mount path if it was set
                 if (result.outletMountPath && !this.outletMountPath) {
                     this.outletMountPath = result.outletMountPath;
                 }
@@ -1270,22 +1252,16 @@ class StackManager extends React.PureComponent {
         return this.outletMountPath;
     }
     /**
-     * Finds the entering and leaving view items for a route transition,
-     * handling special redirect cases.
+     * Finds the entering and leaving view items, handling redirect cases.
      */
     findViewItems(routeInfo) {
         const enteringViewItem = this.context.findViewItemByRouteInfo(routeInfo, this.id);
         let leavingViewItem = this.context.findLeavingViewItemByRouteInfo(routeInfo, this.id);
-        // If we don't have a leaving view item, but the route info indicates
-        // that the user has routed from a previous path, then the leaving view
-        // can be found by the last known pathname.
+        // Try to find leaving view by previous pathname
         if (!leavingViewItem && routeInfo.prevRouteLastPathname) {
             leavingViewItem = this.context.findViewItemByPathname(routeInfo.prevRouteLastPathname, this.id);
         }
-        // Special case for redirects: When a redirect happens inside a nested route,
-        // the entering and leaving view might be the same (the container route like tabs/*).
-        // In this case, we need to look at prevRouteLastPathname to find the actual
-        // view we're transitioning away from.
+        // For redirects where entering === leaving, find the actual previous view
         if (enteringViewItem &&
             leavingViewItem &&
             enteringViewItem === leavingViewItem &&
@@ -1296,8 +1272,7 @@ class StackManager extends React.PureComponent {
                 leavingViewItem = actualLeavingView;
             }
         }
-        // Also check if we're in a redirect scenario where entering and leaving are different
-        // but we still need to handle the actual previous view.
+        // Handle redirect scenario with no leaving view
         if (enteringViewItem &&
             !leavingViewItem &&
             routeInfo.routeAction === 'replace' &&
@@ -1309,9 +1284,6 @@ class StackManager extends React.PureComponent {
         }
         return { enteringViewItem, leavingViewItem };
     }
-    /**
-     * Determines if the leaving view item should be unmounted after a transition.
-     */
     shouldUnmountLeavingView(routeInfo, enteringViewItem, leavingViewItem) {
         var _a, _b, _c, _d;
         if (!leavingViewItem) {
@@ -1320,22 +1292,19 @@ class StackManager extends React.PureComponent {
         if (routeInfo.routeAction === 'replace') {
             const enteringRoutePath = (_b = (_a = enteringViewItem === null || enteringViewItem === void 0 ? void 0 : enteringViewItem.reactElement) === null || _a === void 0 ? void 0 : _a.props) === null || _b === void 0 ? void 0 : _b.path;
             const leavingRoutePath = (_d = (_c = leavingViewItem === null || leavingViewItem === void 0 ? void 0 : leavingViewItem.reactElement) === null || _c === void 0 ? void 0 : _c.props) === null || _d === void 0 ? void 0 : _d.path;
-            // Never unmount the root path "/" - it's the main entry point for back navigation
+            // Never unmount root path - needed for back navigation
             if (leavingRoutePath === '/' || leavingRoutePath === '') {
                 return false;
             }
             if (enteringRoutePath && leavingRoutePath) {
-                // Get parent paths to check if routes share a common parent
                 const getParentPath = (path) => {
-                    const normalized = path.replace(/\/\*$/, ''); // Remove trailing /*
+                    const normalized = path.replace(/\/\*$/, '');
                     const lastSlash = normalized.lastIndexOf('/');
                     return lastSlash > 0 ? normalized.substring(0, lastSlash) : '/';
                 };
                 const enteringParent = getParentPath(enteringRoutePath);
                 const leavingParent = getParentPath(leavingRoutePath);
-                // Unmount if:
-                // 1. Routes are siblings (same parent, e.g., /page1 and /page2, or /foo/page1 and /foo/page2)
-                // 2. Entering is a child of leaving (redirect, e.g., /tabs -> /tabs/tab1)
+                // Unmount if routes are siblings or entering is a child of leaving (redirect)
                 const areSiblings = enteringParent === leavingParent && enteringParent !== '/';
                 const isChildRedirect = enteringRoutePath.startsWith(leavingRoutePath) ||
                     (leavingRoutePath.endsWith('/*') && enteringRoutePath.startsWith(leavingRoutePath.slice(0, -2)));
@@ -1343,7 +1312,7 @@ class StackManager extends React.PureComponent {
             }
             return false;
         }
-        // For non-replace actions, only unmount for back navigation (not forward push)
+        // For non-replace actions, only unmount for back navigation
         const isForwardPush = routeInfo.routeAction === 'push' && routeInfo.routeDirection === 'forward';
         if (!isForwardPush && routeInfo.routeDirection !== 'none' && enteringViewItem !== leavingViewItem) {
             return true;
@@ -1351,21 +1320,17 @@ class StackManager extends React.PureComponent {
         return false;
     }
     /**
-     * Handles the case when the outlet is out of scope (current route is outside mount path).
-     * Returns true if the transition should be aborted.
+     * Handles out-of-scope outlet. Returns true if transition should be aborted.
      */
     handleOutOfScopeOutlet(routeInfo) {
         if (!this.outletMountPath || routeInfo.pathname.startsWith(this.outletMountPath)) {
             return false;
         }
-        // Clear any pending unmount timeout to avoid conflicts
         if (this.outOfScopeUnmountTimeout) {
             clearTimeout(this.outOfScopeUnmountTimeout);
             this.outOfScopeUnmountTimeout = undefined;
         }
-        // When an outlet is out of scope, unmount its views immediately
         const allViewsInOutlet = this.context.getViewItemsForOutlet ? this.context.getViewItemsForOutlet(this.id) : [];
-        // Unmount and remove all views in this outlet immediately to avoid leftover content
         allViewsInOutlet.forEach((viewItem) => {
             hideIonPageElement(viewItem.ionPageElement);
             this.context.unMountViewItem(viewItem);
@@ -1374,12 +1339,10 @@ class StackManager extends React.PureComponent {
         return true;
     }
     /**
-     * Handles the case when this is a nested outlet with relative routes but no valid parent path.
-     * Returns true if the transition should be aborted.
+     * Handles nested outlet with relative routes but no parent path. Returns true to abort.
      */
     handleOutOfContextNestedOutlet(parentPath, leavingViewItem) {
         var _a;
-        // Root outlets have IDs like 'routerOutlet' or 'routerOutlet-2'
         const isRootOutlet = this.id.startsWith('routerOutlet');
         if (isRootOutlet || parentPath !== undefined || !this.ionRouterOutlet) {
             return false;
@@ -1391,7 +1354,6 @@ class StackManager extends React.PureComponent {
             return path && !path.startsWith('/') && path !== '*';
         });
         if (hasRelativeRoutes) {
-            // Hide any visible views in this outlet since it's out of scope
             hideIonPageElement(leavingViewItem === null || leavingViewItem === void 0 ? void 0 : leavingViewItem.ionPageElement);
             if (leavingViewItem) {
                 leavingViewItem.mount = false;
@@ -1402,16 +1364,13 @@ class StackManager extends React.PureComponent {
         return false;
     }
     /**
-     * Handles the case when a nested outlet has no matching route.
-     * Returns true if the transition should be aborted.
+     * Handles nested outlet with no matching route. Returns true to abort.
      */
     handleNoMatchingRoute(enteringRoute, enteringViewItem, leavingViewItem) {
-        // Root outlets have IDs like 'routerOutlet' or 'routerOutlet-2'
         const isRootOutlet = this.id.startsWith('routerOutlet');
         if (isRootOutlet || enteringRoute || enteringViewItem) {
             return false;
         }
-        // Hide any visible views in this outlet since it has no matching route
         hideIonPageElement(leavingViewItem === null || leavingViewItem === void 0 ? void 0 : leavingViewItem.ionPageElement);
         if (leavingViewItem) {
             leavingViewItem.mount = false;
@@ -1420,16 +1379,15 @@ class StackManager extends React.PureComponent {
         return true;
     }
     /**
-     * Handles the transition when entering view item has an ion-page element ready.
+     * Handles transition when entering view has ion-page element ready.
      */
     handleReadyEnteringView(routeInfo, enteringViewItem, leavingViewItem, shouldUnmountLeavingViewItem) {
         var _a, _b;
-        // Handle same view item case (e.g., parameterized route changes)
+        // Handle parameterized route changes (same view, different params)
         if (enteringViewItem === leavingViewItem) {
             const routePath = (_b = (_a = enteringViewItem.reactElement) === null || _a === void 0 ? void 0 : _a.props) === null || _b === void 0 ? void 0 : _b.path;
             const isParameterizedRoute = routePath ? routePath.includes(':') : false;
             if (isParameterizedRoute) {
-                // Refresh match metadata so the component receives updated params
                 const updatedMatch = matchComponent(enteringViewItem.reactElement, routeInfo.pathname, true);
                 if (updatedMatch) {
                     enteringViewItem.routeData.match = updatedMatch;
@@ -1443,23 +1401,16 @@ class StackManager extends React.PureComponent {
                 return;
             }
         }
-        // Try to find leaving view using prev route info if still not found
         if (!leavingViewItem && this.props.routeInfo.prevRouteLastPathname) {
             leavingViewItem = this.context.findViewItemByPathname(this.props.routeInfo.prevRouteLastPathname, this.id);
         }
-        // Ensure the entering view is marked as mounted.
-        // This is critical for views that were previously unmounted (e.g., navigating back to home).
-        // When mount=false, the ViewLifeCycleManager doesn't render the IonPage, so the
-        // ionPageElement reference becomes stale. By setting mount=true, we ensure the view
-        // gets re-rendered and a new IonPage is created.
+        // Re-mount views that were previously unmounted (e.g., navigating back to home)
         if (!enteringViewItem.mount) {
             enteringViewItem.mount = true;
         }
-        // Check visibility state BEFORE showing the entering view.
-        // This must be done before showIonPageElement to get accurate visibility state.
+        // Check visibility state BEFORE showing entering view
         const enteringWasVisible = enteringViewItem.ionPageElement && isViewVisible(enteringViewItem.ionPageElement);
         const leavingIsHidden = leavingViewItem !== undefined && leavingViewItem.ionPageElement && !isViewVisible(leavingViewItem.ionPageElement);
-        // Check for duplicate transition
         const currentTransition = {
             enteringId: enteringViewItem.id,
             leavingId: leavingViewItem === null || leavingViewItem === void 0 ? void 0 : leavingViewItem.id,
@@ -1469,91 +1420,56 @@ class StackManager extends React.PureComponent {
             this.lastTransition.leavingId &&
             this.lastTransition.enteringId === currentTransition.enteringId &&
             this.lastTransition.leavingId === currentTransition.leavingId;
-        // Skip transition if entering view was ALREADY visible and leaving view is not visible.
-        // This indicates the transition has already been performed (e.g., via swipe gesture).
-        // IMPORTANT: Only skip if both ionPageElements are the same as when the transition was last done.
-        // If the leaving view's ionPageElement changed (e.g., component re-rendered with different IonPage),
-        // we should NOT skip because the DOM state is inconsistent.
+        // Skip if transition already performed (e.g., via swipe gesture)
         if (enteringWasVisible && leavingIsHidden && isDuplicateTransition) {
-            // For swipe-to-go-back, the transition animation was handled by the gesture.
-            // We still need to set mount=false so React unmounts the leaving view.
-            // Only do this when skipTransition is set (indicating gesture completion).
             if (this.skipTransition &&
                 shouldUnmountLeavingViewItem &&
                 leavingViewItem &&
                 enteringViewItem !== leavingViewItem) {
                 leavingViewItem.mount = false;
-                // Call transitionPage with duration 0 to trigger ionViewDidLeave lifecycle
-                // which is needed for ViewLifeCycleManager to remove the view.
+                // Trigger ionViewDidLeave lifecycle for ViewLifeCycleManager cleanup
                 this.transitionPage(routeInfo, enteringViewItem, leavingViewItem, 'back');
             }
-            // Clear skipTransition since we're not calling transitionPage which normally clears it
             this.skipTransition = false;
-            // Must call forceUpdate to trigger re-render after mount state change
             this.forceUpdate();
             return;
         }
-        // Ensure the entering view is not hidden from previous navigations
-        // This must happen AFTER the visibility check above
         showIonPageElement(enteringViewItem.ionPageElement);
-        // Skip if this is a duplicate transition (but visibility state didn't match above)
-        // OR if skipTransition is set (swipe gesture already handled the animation)
+        // Handle duplicate transition or swipe gesture completion
         if (isDuplicateTransition || this.skipTransition) {
-            // For swipe-to-go-back, we still need to handle unmounting even if visibility
-            // conditions aren't fully met (animation might still be in progress)
             if (this.skipTransition &&
                 shouldUnmountLeavingViewItem &&
                 leavingViewItem &&
                 enteringViewItem !== leavingViewItem) {
                 leavingViewItem.mount = false;
-                // For swipe-to-go-back, we need to call transitionPage with duration 0 to
-                // trigger the ionViewDidLeave lifecycle event. The ViewLifeCycleManager
-                // uses componentCanBeDestroyed callback to remove the view, which is
-                // only called from ionViewDidLeave. Since the gesture animation already
-                // completed before mount=false was set, we need to re-fire the lifecycle.
+                // Re-fire ionViewDidLeave since gesture completed before mount=false was set
                 this.transitionPage(routeInfo, enteringViewItem, leavingViewItem, 'back');
             }
-            // Clear skipTransition since we're not calling transitionPage which normally clears it
             this.skipTransition = false;
-            // Must call forceUpdate to trigger re-render after mount state change
             this.forceUpdate();
             return;
         }
         this.lastTransition = currentTransition;
         this.transitionPage(routeInfo, enteringViewItem, leavingViewItem);
-        // Handle unmounting the leaving view
         if (shouldUnmountLeavingViewItem && leavingViewItem && enteringViewItem !== leavingViewItem) {
             leavingViewItem.mount = false;
             this.handleLeavingViewUnmount(routeInfo, enteringViewItem, leavingViewItem);
         }
-        // Clean up any orphaned sibling views that are no longer reachable
-        // This is important for replace actions (like redirects) where sibling views
-        // that were pushed earlier become unreachable
+        // Clean up orphaned sibling views after replace actions (redirects)
         this.cleanupOrphanedSiblingViews(routeInfo, enteringViewItem, leavingViewItem);
     }
     /**
-     * Handles the delayed unmount of the leaving view item.
-     * For 'replace' actions: handles container route transitions specially.
-     * For back navigation: explicitly unmounts because the ionViewDidLeave lifecycle
-     * fires DURING transitionPage, but mount=false is set AFTER.
-     *
-     * @param routeInfo Current route information
-     * @param enteringViewItem The view being navigated to
-     * @param leavingViewItem The view being navigated from
+     * Handles leaving view unmount for replace actions.
      */
     handleLeavingViewUnmount(routeInfo, enteringViewItem, leavingViewItem) {
         var _a, _b, _c, _d, _e, _f;
         if (!leavingViewItem.ionPageElement) {
             return;
         }
-        // For push/pop actions, do NOT unmount - views are cached for navigation history.
-        // Push: Forward navigation caches views for back navigation
-        // Pop: Back navigation should not unmount the entering view's history
-        // Only 'replace' actions should actually unmount views since they replace history.
+        // Only replace actions unmount views; push/pop cache for navigation history
         if (routeInfo.routeAction !== 'replace') {
             return;
         }
-        // For replace actions, check if we should skip removal for nested outlet redirects
         const enteringRoutePath = (_b = (_a = enteringViewItem.reactElement) === null || _a === void 0 ? void 0 : _a.props) === null || _b === void 0 ? void 0 : _b.path;
         const leavingRoutePath = (_d = (_c = leavingViewItem.reactElement) === null || _c === void 0 ? void 0 : _c.props) === null || _d === void 0 ? void 0 : _d.path;
         const isEnteringContainerRoute = enteringRoutePath && enteringRoutePath.endsWith('/*');
@@ -1570,41 +1486,43 @@ class StackManager extends React.PureComponent {
         const viewToUnmount = leavingViewItem;
         setTimeout(() => {
             this.context.unMountViewItem(viewToUnmount);
-            // Trigger re-render to remove the view from DOM
             this.forceUpdate();
         }, VIEW_UNMOUNT_DELAY_MS);
     }
     /**
-     * Cleans up orphaned sibling views after a replace action.
-     * When navigating via replace (e.g., through a redirect), sibling views that were
-     * pushed earlier may become orphaned (unreachable via back navigation).
-     * This method identifies and unmounts such views.
+     * Cleans up orphaned sibling views after replace actions or push-to-container navigations.
      */
     cleanupOrphanedSiblingViews(routeInfo, enteringViewItem, leavingViewItem) {
-        var _a, _b, _c, _d;
-        // Only cleanup for replace actions
-        if (routeInfo.routeAction !== 'replace') {
-            return;
-        }
+        var _a, _b, _c, _d, _e, _f, _g;
         const enteringRoutePath = (_b = (_a = enteringViewItem.reactElement) === null || _a === void 0 ? void 0 : _a.props) === null || _b === void 0 ? void 0 : _b.path;
         if (!enteringRoutePath) {
             return;
         }
-        // Get all views in this outlet
+        const leavingRoutePath = (_d = (_c = leavingViewItem === null || leavingViewItem === void 0 ? void 0 : leavingViewItem.reactElement) === null || _c === void 0 ? void 0 : _c.props) === null || _d === void 0 ? void 0 : _d.path;
+        const isContainerRoute = (path) => path === null || path === void 0 ? void 0 : path.endsWith('/*');
+        const isReplaceAction = routeInfo.routeAction === 'replace';
+        const isPushToContainer = routeInfo.routeAction === 'push' && routeInfo.routeDirection === 'none' && isContainerRoute(enteringRoutePath);
+        if (!isReplaceAction && !isPushToContainer) {
+            return;
+        }
+        // Skip cleanup for tab switches
+        const isSameView = enteringViewItem === leavingViewItem;
+        const isSameContainerRoute = isContainerRoute(enteringRoutePath) && leavingRoutePath === enteringRoutePath;
+        const isNavigatingWithinContainer = isPushToContainer &&
+            !leavingViewItem &&
+            ((_e = routeInfo.prevRouteLastPathname) === null || _e === void 0 ? void 0 : _e.startsWith(enteringRoutePath.replace(/\/\*$/, '')));
+        if (isSameView || isSameContainerRoute || isNavigatingWithinContainer) {
+            return;
+        }
         const allViewsInOutlet = this.context.getViewItemsForOutlet ? this.context.getViewItemsForOutlet(this.id) : [];
-        // Check if routes are "siblings" - direct children of the same outlet at the same level
         const areSiblingRoutes = (path1, path2) => {
-            // Both are relative routes (don't start with /)
             const path1IsRelative = !path1.startsWith('/');
             const path2IsRelative = !path2.startsWith('/');
-            // For relative routes at the outlet root level, they're siblings
             if (path1IsRelative && path2IsRelative) {
-                // Check if they're at the same depth (no nested slashes, except for wildcards)
                 const path1Depth = path1.replace(/\/\*$/, '').split('/').filter(Boolean).length;
                 const path2Depth = path2.replace(/\/\*$/, '').split('/').filter(Boolean).length;
                 return path1Depth === path2Depth && path1Depth <= 1;
             }
-            // For absolute routes, check if they share the same parent
             const getParent = (path) => {
                 const normalized = path.replace(/\/\*$/, '');
                 const lastSlash = normalized.lastIndexOf('/');
@@ -1613,13 +1531,7 @@ class StackManager extends React.PureComponent {
             return getParent(path1) === getParent(path2);
         };
         for (const viewItem of allViewsInOutlet) {
-            const viewRoutePath = (_d = (_c = viewItem.reactElement) === null || _c === void 0 ? void 0 : _c.props) === null || _d === void 0 ? void 0 : _d.path;
-            // Skip views that shouldn't be cleaned up:
-            // - The entering view itself
-            // - The immediate leaving view (handled separately by handleLeavingViewUnmount)
-            // - Already unmounted views
-            // - Views without a route path
-            // - Container routes (ending in /*) when entering is also a container route
+            const viewRoutePath = (_g = (_f = viewItem.reactElement) === null || _f === void 0 ? void 0 : _f.props) === null || _g === void 0 ? void 0 : _g.path;
             const shouldSkip = viewItem.id === enteringViewItem.id ||
                 (leavingViewItem && viewItem.id === leavingViewItem.id) ||
                 !viewItem.mount ||
@@ -1628,12 +1540,9 @@ class StackManager extends React.PureComponent {
             if (shouldSkip) {
                 continue;
             }
-            // Check if this is a sibling route that should be cleaned up
             if (areSiblingRoutes(enteringRoutePath, viewRoutePath)) {
-                // Hide and unmount the orphaned view
                 hideIonPageElement(viewItem.ionPageElement);
                 viewItem.mount = false;
-                // Schedule removal
                 const viewToRemove = viewItem;
                 setTimeout(() => {
                     this.context.unMountViewItem(viewToRemove);
@@ -1643,7 +1552,7 @@ class StackManager extends React.PureComponent {
         }
     }
     /**
-     * Handles the case when entering view has no ion-page element yet (waiting for render).
+     * Handles entering view with no ion-page element yet (waiting for render).
      */
     handleWaitingForIonPage(routeInfo, enteringViewItem, leavingViewItem, shouldUnmountLeavingViewItem) {
         var _a, _b;
@@ -1858,6 +1767,18 @@ class StackManager extends React.PureComponent {
      * @param routeInfo The route information that associates with `<IonPage>`.
      */
     registerIonPage(page, routeInfo) {
+        /**
+         * DO NOT remove ion-page-invisible here.
+         *
+         * PageManager.componentDidMount adds ion-page-invisible before calling registerIonPage.
+         * At this point, the <IonPage> div exists but its CHILDREN (header, toolbar, menu-button)
+         * have NOT rendered yet. If we remove ion-page-invisible now, the page becomes visible
+         * with empty/incomplete content, causing a flicker (especially for ion-menu-button which
+         * starts with menu-button-hidden class).
+         *
+         * Instead, let transitionPage handle visibility AFTER waiting for components to be ready.
+         * This ensures the page only becomes visible when its content is fully rendered.
+         */
         this.waitingForIonPage = false;
         if (this.ionPageWaitTimeout) {
             clearTimeout(this.ionPageWaitTimeout);
@@ -1894,8 +1815,7 @@ class StackManager extends React.PureComponent {
         this.handlePageTransition(routeInfo);
     }
     /**
-     * Determines if a new IonPage registration should be rejected as orphaned.
-     * This happens when a component re-renders with a different IonPage while navigating away.
+     * Checks if a new IonPage should be rejected (component re-rendered while navigating away).
      */
     shouldRejectOrphanedPage(newPage, oldPageElement, routeInfo) {
         if (!oldPageElement || oldPageElement === newPage) {
@@ -1903,16 +1823,11 @@ class StackManager extends React.PureComponent {
         }
         const newPageId = newPage.getAttribute('data-pageid');
         const oldPageId = oldPageElement.getAttribute('data-pageid');
-        // Only reject if both pageIds exist and are different
         if (!newPageId || !oldPageId || newPageId === oldPageId) {
             return false;
         }
-        // Reject only if we're navigating away from this route
         return this.props.routeInfo.pathname !== routeInfo.pathname;
     }
-    /**
-     * Hides an orphaned IonPage and schedules its removal from the DOM.
-     */
     hideAndRemoveOrphanedPage(page) {
         page.classList.add('ion-page-hidden');
         page.setAttribute('aria-hidden', 'true');
@@ -1923,40 +1838,25 @@ class StackManager extends React.PureComponent {
         }, VIEW_UNMOUNT_DELAY_MS);
     }
     /**
-     * Configures the router outlet for the swipe-to-go-back gesture.
-     *
-     * @param routerOutlet The Ionic router outlet component: `<IonRouterOutlet>`.
+     * Configures swipe-to-go-back gesture for the router outlet.
      */
     async setupRouterOutlet(routerOutlet) {
         const canStart = () => {
             const config = getConfig();
-            // Check if swipe back is enabled in config (default to true for iOS mode)
             const swipeEnabled = config && config.get('swipeBackEnabled', routerOutlet.mode === 'ios');
             if (!swipeEnabled) {
                 return false;
             }
             const { routeInfo } = this.props;
             const swipeBackRouteInfo = this.getSwipeBackRouteInfo();
-            // First try to find the view in the current outlet
             let enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, this.id, false);
-            // If not found in current outlet, search all outlets (for cross-outlet swipe back)
             if (!enteringViewItem) {
                 enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, undefined, false);
             }
-            // Check if the ionPageElement is still in the document.
-            // A view might have mount=false but still have its ionPageElement in the DOM
-            // (due to timing differences in unmounting).
+            // View might have mount=false but ionPageElement still in DOM
             const ionPageInDocument = Boolean((enteringViewItem === null || enteringViewItem === void 0 ? void 0 : enteringViewItem.ionPageElement) && document.body.contains(enteringViewItem.ionPageElement));
             const canStartSwipe = !!enteringViewItem &&
-                // Check if we can swipe to this view. Either:
-                // 1. The view is mounted (mount=true), OR
-                // 2. The view's ionPageElement is still in the document
-                // The second case handles views that have been marked for unmount but haven't
-                // actually been removed from the DOM yet.
                 (enteringViewItem.mount || ionPageInDocument) &&
-                // When on the first page it is possible for findViewItemByRouteInfo to
-                // return the exact same view you are currently on.
-                // Make sure that we are not swiping back to the same instances of a view.
                 enteringViewItem.routeData.match.pattern.path !== routeInfo.pathname;
             return canStartSwipe;
         };
@@ -2064,9 +1964,7 @@ class StackManager extends React.PureComponent {
         const directionToUse = direction !== null && direction !== void 0 ? direction : routeInfoFallbackDirection;
         if (enteringViewItem && enteringViewItem.ionPageElement && this.routerOutletElement) {
             if (leavingViewItem && leavingViewItem.ionPageElement && enteringViewItem === leavingViewItem) {
-                // If a page is transitioning to another version of itself
-                // we clone it so we can have an animation to show
-                // (e.g., `/user/1` → `/user/2`)
+                // Clone page for same-view transitions (e.g., /user/1 → /user/2)
                 const match = matchComponent(leavingViewItem.reactElement, routeInfo.pathname);
                 if (match) {
                     const newLeavingElement = clonePageElement(leavingViewItem.ionPageElement.outerHTML);
@@ -2077,23 +1975,98 @@ class StackManager extends React.PureComponent {
                     }
                 }
                 else {
-                    /**
-                     * The route no longer matches the component type of the leaving view.
-                     * (e.g., `/user/1` → `/settings`)
-                     *
-                     * This can also occur in edge cases like rapid navigation
-                     * or during parent component re-renders that briefly cause
-                     * the view items to be the same instance before the final
-                     * route component is determined.
-                     */
+                    // Route no longer matches (e.g., /user/1 → /settings)
                     await runCommit(enteringViewItem.ionPageElement, undefined);
                 }
             }
             else {
-                await runCommit(enteringViewItem.ionPageElement, leavingViewItem === null || leavingViewItem === void 0 ? void 0 : leavingViewItem.ionPageElement);
-                if (leavingViewItem && leavingViewItem.ionPageElement && !progressAnimation) {
-                    leavingViewItem.ionPageElement.classList.add('ion-page-hidden');
-                    leavingViewItem.ionPageElement.setAttribute('aria-hidden', 'true');
+                const leavingEl = leavingViewItem === null || leavingViewItem === void 0 ? void 0 : leavingViewItem.ionPageElement;
+                // For non-animated transitions, don't pass leaving element to commit() to avoid
+                // flicker caused by commit() briefly unhiding the leaving page
+                const isNonAnimatedTransition = directionToUse === undefined && !progressAnimation;
+                if (isNonAnimatedTransition && leavingEl) {
+                    /**
+                     * Flicker prevention for non-animated transitions:
+                     * 1. Keep entering invisible during commit and component mounting
+                     * 2. Wait for components (including menu button) to be ready
+                     * 3. Swap visibility atomically
+                     */
+                    const enteringEl = enteringViewItem.ionPageElement;
+                    enteringEl.classList.add('ion-page');
+                    if (!enteringEl.classList.contains('ion-page-invisible')) {
+                        enteringEl.classList.add('ion-page-invisible');
+                    }
+                    enteringEl.classList.remove('ion-page-hidden');
+                    enteringEl.removeAttribute('aria-hidden');
+                    await routerOutlet.commit(enteringEl, undefined, {
+                        duration: 0,
+                        direction: undefined,
+                        showGoBack: !!routeInfo.pushedByRoute,
+                        progressAnimation: false,
+                        animationBuilder: routeInfo.routeAnimation,
+                    });
+                    // Re-add invisible after commit removes it (commit's afterTransition handling)
+                    enteringEl.classList.add('ion-page-invisible');
+                    /**
+                     * Wait for components to be ready. Menu buttons start hidden (menu-button-hidden)
+                     * and become visible after componentDidLoad. Wait for hydration and visibility.
+                     */
+                    const waitForComponentsReady = () => {
+                        return new Promise((resolve) => {
+                            const checkReady = () => {
+                                const ionicComponents = enteringEl.querySelectorAll('ion-header, ion-toolbar, ion-buttons, ion-menu-button, ion-title, ion-content');
+                                const allHydrated = Array.from(ionicComponents).every((el) => el.classList.contains('hydrated'));
+                                const menuButtons = enteringEl.querySelectorAll('ion-menu-button');
+                                const menuButtonsReady = Array.from(menuButtons).every((el) => !el.classList.contains('menu-button-hidden'));
+                                return allHydrated && menuButtonsReady;
+                            };
+                            if (checkReady()) {
+                                resolve();
+                                return;
+                            }
+                            let resolved = false;
+                            const observer = new MutationObserver(() => {
+                                if (!resolved && checkReady()) {
+                                    resolved = true;
+                                    observer.disconnect();
+                                    resolve();
+                                }
+                            });
+                            observer.observe(enteringEl, {
+                                subtree: true,
+                                attributes: true,
+                                attributeFilter: ['class'],
+                            });
+                            setTimeout(() => {
+                                if (!resolved) {
+                                    resolved = true;
+                                    observer.disconnect();
+                                    resolve();
+                                }
+                            }, 100);
+                        });
+                    };
+                    await waitForComponentsReady();
+                    // Swap visibility in sync with browser's render cycle
+                    await new Promise((resolve) => {
+                        requestAnimationFrame(() => {
+                            enteringEl.classList.remove('ion-page-invisible');
+                            // Second rAF ensures entering is painted before hiding leaving
+                            requestAnimationFrame(() => {
+                                leavingEl.classList.add('ion-page-hidden');
+                                leavingEl.setAttribute('aria-hidden', 'true');
+                                resolve();
+                            });
+                        });
+                    });
+                }
+                else {
+                    await runCommit(enteringViewItem.ionPageElement, leavingEl);
+                    // For animated transitions, hide leaving element after commit completes
+                    if (leavingEl && !progressAnimation) {
+                        leavingEl.classList.add('ion-page-hidden');
+                        leavingEl.setAttribute('aria-hidden', 'true');
+                    }
                 }
             }
         }