fix(react-router): stop hidden views from re-rendering on every navigation

packages/react-router/src/ReactRouter/IonRouter.tsx

@@ -23,6 +23,8 @@ import { useLocation, useNavigate } from 'react-router-dom';
 import { IonRouteInner } from './IonRouteInner';
 import { ReactRouterViewStack } from './ReactRouterViewStack';
 import StackManager from './StackManager';
+import { areParamsEqual } from './utils/areParamsEqual';
+import type { RouteParams } from './utils/areParamsEqual';
 
 // Use Location directly - state is typed as `unknown` in history v5
 type HistoryLocation = Location;
@@ -36,7 +38,6 @@ interface IonRouterProps {
   registerHistoryListener: (cb: (location: HistoryLocation, action: HistoryAction) => void) => void;
 }
 
-type RouteParams = Record<string, string | string[] | undefined>;
 type SafeRouteParams = Record<string, string | string[]>;
 
 const filterUndefinedParams = (params: RouteParams): SafeRouteParams => {
@@ -73,29 +74,6 @@ const checkIsMultiStepBack = (
   return false;
 };
 
-const areParamsEqual = (a?: RouteParams, b?: RouteParams) => {
-  const paramsA = a || {};
-  const paramsB = b || {};
-  const keysA = Object.keys(paramsA);
-  const keysB = Object.keys(paramsB);
-
-  if (keysA.length !== keysB.length) {
-    return false;
-  }
-
-  return keysA.every((key) => {
-    const valueA = paramsA[key];
-    const valueB = paramsB[key];
-    if (Array.isArray(valueA) && Array.isArray(valueB)) {
-      if (valueA.length !== valueB.length) {
-        return false;
-      }
-      return valueA.every((entry, idx) => entry === valueB[idx]);
-    }
-    return valueA === valueB;
-  });
-};
-
 export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildren<IonRouterProps>) => {
   const location = useLocation();
   const navigate = useNavigate();

packages/react-router/src/ReactRouter/ReactRouterViewStack.tsx

@@ -11,6 +11,7 @@ import React from 'react';
 import type { PathMatch } from 'react-router';
 import { Navigate, UNSAFE_RouteContext as RouteContext } from 'react-router-dom';
 
+import { areParamsEqual } from './utils/areParamsEqual';
 import { analyzeRouteChildren, computeParentPath } from './utils/computeParentPath';
 import { derivePathnameToMatch, matchPath } from './utils/pathMatching';
 import { normalizePathnameForComparison } from './utils/pathNormalization';
@@ -218,6 +219,54 @@ const resolveIndexRouteMatch = (
   return normalizedPathname === normalizedBase ? previousMatch : null;
 };
 
+const shallowEqual = (a: object, b: object): boolean => {
+  const aRecord = a as Record<string, unknown>;
+  const bRecord = b as Record<string, unknown>;
+  const aKeys = Object.keys(aRecord);
+  return aKeys.length === Object.keys(bRecord).length && aKeys.every((key) => aRecord[key] === bRecord[key]);
+};
+
+const isSameMatch = (a: RouteContextMatch, b: RouteContextMatch): boolean =>
+  a === b ||
+  (a.pathname === b.pathname &&
+    a.pathnameBase === b.pathnameBase &&
+    areParamsEqual(a.params, b.params) &&
+    (a.route === b.route || shallowEqual(a.route, b.route)));
+
+/**
+ * The outlet rebuilds a view's `RouteContext` several times per navigation, so
+ * this compares by content to tell whether anything actually changed.
+ */
+const isSameRouteContext = (
+  a: React.ContextType<typeof RouteContext>,
+  b: React.ContextType<typeof RouteContext>
+): boolean => {
+  const { matches: aMatches, ...aRest } = a;
+  const { matches: bMatches, ...bRest } = b;
+  return (
+    aMatches.length === bMatches.length &&
+    shallowEqual(aRest, bRest) &&
+    aMatches.every((match, i) => isSameMatch(match as RouteContextMatch, bMatches[i] as RouteContextMatch))
+  );
+};
+
+/**
+ * Reuses the last `RouteContext` while its content is the same or `hold` is set,
+ * so hidden pages that only call `useParams` don't re-render. It lives in
+ * component state because outlets with the same id share view items.
+ */
+const ViewRouteContextProvider: React.FC<{
+  value: React.ContextType<typeof RouteContext>;
+  hold: boolean;
+  children: React.ReactNode;
+}> = ({ value, hold, children }) => {
+  const [heldValue, setHeldValue] = React.useState(value);
+  if (!hold && heldValue !== value && !isSameRouteContext(heldValue, value)) {
+    setHeldValue(value);
+  }
+  return <RouteContext.Provider value={heldValue}>{children}</RouteContext.Provider>;
+};
+
 export class ReactRouterViewStack extends ViewStacks {
   /**
    * Stores the computed parent path for each outlet.
@@ -452,6 +501,9 @@ export class ReactRouterViewStack extends ViewStacks {
       viewItem.routeData.match = match;
     }
 
+    // A more specific sibling owns the pathname, so this view is hidden even though it matches.
+    let hiddenBySpecificMatch = false;
+
     // Deactivate wildcard (catch-all) and empty-path (default) routes when a more-specific route matches.
     // This prevents "Not found" or fallback pages from showing alongside valid routes.
     if (routePath === '*' || routePath === '/*' || routePath === '') {
@@ -511,6 +563,7 @@ export class ReactRouterViewStack extends ViewStacks {
       }
 
       if (hasSpecificMatch && !isSwipeRevealed(viewItem)) {
+        hiddenBySpecificMatch = true;
         // A splat can be the outlet's container page rather than a "not found" fallback.
         // Pushed over it is the page underneath, so unmounting it destroys its state and
         // leaves nothing for back to reveal. Hiding it below covers that. A view with no
@@ -534,6 +587,11 @@ export class ReactRouterViewStack extends ViewStacks {
       viewItem.routeData.match = match;
     }
     const routeMatch = shouldSkipForDifferentParam ? viewItem.routeData?.match : match || viewItem.routeData?.match;
+    // Hold the context when a sibling owns the pathname, the view is parked on another param
+    // instance, or it doesn't match. A pathless default only strictly matches at "/", so no match
+    // there doesn't mean it's hidden.
+    const isPathlessDefault = !routePath && !viewItem.routeData?.childProps?.index;
+    const holdRouteContext = hiddenBySpecificMatch || !!shouldSkipForDifferentParam || (!match && !isPathlessDefault);
 
     return (
       <RouteContext.Consumer key={`view-context-${viewItem.id}`}>
@@ -581,7 +639,9 @@ export class ReactRouterViewStack extends ViewStacks {
               mount={viewItem.mount}
               removeView={() => this.remove(viewItem)}
             >
-              <RouteContext.Provider value={routeContextValue}>{componentElement}</RouteContext.Provider>
+              <ViewRouteContextProvider value={routeContextValue} hold={holdRouteContext}>
+                {componentElement}
+              </ViewRouteContextProvider>
             </ViewLifeCycleManager>
           );
         }}

packages/react-router/src/ReactRouter/utils/areParamsEqual.ts

@@ -0,0 +1,27 @@
+export type RouteParams = Record<string, string | string[] | undefined>;
+
+/**
+ * Compares two route param objects by value, treating a missing object as empty.
+ */
+export const areParamsEqual = (a?: RouteParams, b?: RouteParams): boolean => {
+  const paramsA = a || {};
+  const paramsB = b || {};
+  const keysA = Object.keys(paramsA);
+  const keysB = Object.keys(paramsB);
+
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  return keysA.every((key) => {
+    const valueA = paramsA[key];
+    const valueB = paramsB[key];
+    if (Array.isArray(valueA) && Array.isArray(valueB)) {
+      if (valueA.length !== valueB.length) {
+        return false;
+      }
+      return valueA.every((entry, idx) => entry === valueB[idx]);
+    }
+    return valueA === valueB;
+  });
+};

packages/react-router/test/base/src/App.tsx

@@ -48,6 +48,7 @@ import DirectionNoneBack from './pages/direction-none-back/DirectionNoneBack';
 import TabSearchParams from './pages/tab-search-params/TabSearchParams';
 import { Step1, Step2, Step3, Step4 } from './pages/replace-params/ReplaceParams';
 import { ParamSwipeBack, ParamSwipeBackB } from './pages/param-swipe-back/ParamSwipeBack';
+import HiddenViewRenders from './pages/hidden-view-renders/HiddenViewRenders';
 import TabLifecycle from './pages/tab-lifecycle/TabLifecycle';
 import TabLifecycleOutside from './pages/tab-lifecycle/TabLifecycleOutside';
 import {
@@ -121,6 +122,7 @@ const App: React.FC = () => {
           <Route path="/replace-params" element={<Navigate to="/replace-params/step1" replace />} />
           <Route path="/tab-lifecycle/*" element={<TabLifecycle />} />
           <Route path="/tab-lifecycle-outside" element={<TabLifecycleOutside />} />
+          <Route path="/hidden-view-renders/*" element={<HiddenViewRenders />} />
           <Route path="/router-link-modifier-click" element={<RouterLinkModifierClick />} />
           <Route path="/router-link-modifier-click/target" element={<RouterLinkModifierClickTarget />} />
           <Route path="/navigate-root/page-a" element={<NavigateRootPageA />} />

packages/react-router/test/base/src/pages/Main.tsx

@@ -94,6 +94,9 @@ const Main: React.FC = () => {
           <IonItem routerLink="/tab-lifecycle">
             <IonLabel>Tab Lifecycle</IonLabel>
           </IonItem>
+          <IonItem routerLink="/hidden-view-renders">
+            <IonLabel>Hidden View Renders</IonLabel>
+          </IonItem>
         </IonList>
 
         <IonList>

packages/react-router/test/base/src/pages/hidden-view-renders/HiddenViewRenders.tsx

@@ -0,0 +1,114 @@
+import {
+  IonTabs,
+  IonRouterOutlet,
+  IonTabBar,
+  IonTabButton,
+  IonLabel,
+  IonPage,
+  IonHeader,
+  IonToolbar,
+  IonTitle,
+  IonContent,
+  IonButton,
+  useIonRouter,
+} from '@ionic/react';
+import React, { useEffect } from 'react';
+import { Route, Navigate, useParams } from 'react-router-dom';
+
+import TestDescription from '../../components/TestDescription';
+import { countRender } from '../../utils';
+
+/**
+ * Counts committed renders. An effect with no dependency list runs once per
+ * commit, so a render that bails out isn't counted.
+ */
+const useCommitCounter = (id: string) => {
+  useEffect(() => countRender(id));
+};
+
+const ParamsReader: React.FC<{ tab: string }> = ({ tab }) => {
+  useParams();
+  useCommitCounter(`${tab}:params`);
+  return null;
+};
+
+const IonRouterReader: React.FC<{ tab: string }> = ({ tab }) => {
+  useIonRouter();
+  useCommitCounter(`${tab}:ionRouter`);
+  return null;
+};
+
+const TabPage: React.FC<{ tab: string }> = ({ tab }) => {
+  return (
+    <IonPage data-pageid={`hidden-view-renders-${tab}`}>
+      <IonHeader>
+        <IonToolbar>
+          <IonTitle>Tab {tab.toUpperCase()}</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent>
+        <ParamsReader tab={tab} />
+        <IonRouterReader tab={tab} />
+        <TestDescription>
+          Switch between Tabs A, B and C a few times. Hidden pages that read useParams should not re-render, and ones
+          that read useIonRouter should re-render once per switch. Counts are in window.renderCounts.
+        </TestDescription>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+const SplatPage: React.FC = () => {
+  const params = useParams();
+  useCommitCounter('d:params');
+
+  return (
+    <IonPage data-pageid="hidden-view-renders-d">
+      <IonHeader>
+        <IonToolbar>
+          <IonTitle>Tab D</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent>
+        <div id="splat-param">{params['*']}</div>
+        <IonButton routerLink="/hidden-view-renders/d/two" id="go-to-d-two">
+          Go to D Two
+        </IonButton>
+        <TestDescription>
+          Tap Go to D Two. The splat param above should change to "two", and window.renderCounts['d:params'] should go
+          up by 1.
+        </TestDescription>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+const HiddenViewRenders: React.FC = () => {
+  return (
+    <IonTabs data-pageid="hidden-view-renders">
+      <IonRouterOutlet id="hidden-view-renders">
+        <Route index element={<Navigate to="/hidden-view-renders/a" replace />} />
+        <Route path="a" element={<TabPage tab="a" />} />
+        <Route path="b" element={<TabPage tab="b" />} />
+        <Route path="c" element={<TabPage tab="c" />} />
+        <Route path="d/*" element={<SplatPage />} />
+      </IonRouterOutlet>
+      <IonTabBar slot="bottom">
+        <IonTabButton tab="a" href="/hidden-view-renders/a">
+          <IonLabel>Tab A</IonLabel>
+        </IonTabButton>
+        <IonTabButton tab="b" href="/hidden-view-renders/b">
+          <IonLabel>Tab B</IonLabel>
+        </IonTabButton>
+        <IonTabButton tab="c" href="/hidden-view-renders/c">
+          <IonLabel>Tab C</IonLabel>
+        </IonTabButton>
+        <IonTabButton tab="d" href="/hidden-view-renders/d/one">
+          <IonLabel>Tab D</IonLabel>
+        </IonTabButton>
+      </IonTabBar>
+    </IonTabs>
+  );
+};
+
+export default HiddenViewRenders;

packages/react-router/test/base/src/utils/index.ts

@@ -1,3 +1,4 @@
 export * from './generateId';
 export * from './lifecycleEvents';
 export * from './dev';
+export * from './renderCounts';

packages/react-router/test/base/src/utils/renderCounts.ts

@@ -0,0 +1,5 @@
+/** Records a committed render under `id` on `window.renderCounts` for a spec to assert on. */
+export const countRender = (id: string) => {
+  (window as any).renderCounts = (window as any).renderCounts || {};
+  (window as any).renderCounts[id] = ((window as any).renderCounts[id] ?? 0) + 1;
+};