Refactored state management for StatefulShellRoute.

Removed some obsolete code.

packages/go_router/example/lib/stateful_shell_route.dart

@@ -44,9 +44,6 @@ class NestedTabNavigationExampleApp extends StatelessWidget {
         branches: <StatefulShellBranch>[
           /// The route branch for the first tab of the bottom navigation bar.
           StatefulShellBranch(
-            /// To enable preloading of the initial locations of branches, pass
-            /// true for the parameter preload.
-            // preload: true,
             navigatorKey: _tabANavigatorKey,
             routes: <RouteBase>[
               GoRoute(
@@ -510,11 +507,6 @@ class TabScreen extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    /// If preloading is enabled on the top StatefulShellRoute, this will be
-    /// printed directly after the app has been started, but only for the route
-    /// that is the initial location ('/c1')
-    debugPrint('Building TabScreen - $label');
-
     return Center(
       child: Column(
         mainAxisSize: MainAxisSize.min,

packages/go_router/lib/src/builder.dart

@@ -68,6 +68,10 @@ class RouteBuilder {
   final Map<GlobalKey<NavigatorState>, HeroController> _goHeroCache =
       <GlobalKey<NavigatorState>, HeroController>{};
 
+  /// State for any active stateful shell routes
+  final Map<ShellRouteBase, Object?> _shellRouteState =
+      <ShellRouteBase, Object?>{};
+
   /// Builds the top-level Navigator for the given [RouteMatchList].
   Widget build(
     BuildContext context,
@@ -154,43 +158,19 @@ class RouteBuilder {
       /// Clean up previous cache to prevent memory leak.
       _goHeroCache.removeWhere(
           (GlobalKey<NavigatorState> key, _) => !keyToPage.keys.contains(key));
-    }
-  }
 
-  /// Builds a preloaded nested [Navigator], containing a sub-tree (beginning
-  /// at startIndex) of the provided route match list.
-  Widget buildPreloadedNestedNavigator(
-      BuildContext context,
-      RouteMatchList matchList,
-      int startIndex,
-      bool routerNeglect,
-      GlobalKey<NavigatorState> navigatorKey,
-      {List<NavigatorObserver>? observers,
-      String? restorationScopeId}) {
-    final Map<GlobalKey<NavigatorState>, List<Page<Object?>>> keyToPage =
-        <GlobalKey<NavigatorState>, List<Page<Object?>>>{};
-    try {
-      final _PagePopContext pagePopContext = _PagePopContext._(onPopPage);
-      _buildRecursive(
-          context,
-          matchList,
-          startIndex,
-          pagePopContext,
-          routerNeglect,
-          keyToPage,
-          navigatorKey, <Page<Object?>, GoRouterState>{});
-
-      return _buildNavigator(
-        pagePopContext.onPopPage,
-        keyToPage[navigatorKey]!,
-        navigatorKey,
-        observers: observers,
-        restorationScopeId: restorationScopeId,
-        heroController: _getHeroController(context),
-      );
-    } on _RouteBuilderError catch (e) {
-      return _buildErrorNavigator(
-          context, e, matchList, onPopPage, configuration.navigatorKey);
+      /// Clean up cache of shell route states, but keep states for shell routes
+      /// in the current match list, as well as in any nested stateful shell
+      /// routes
+      if (_shellRouteState.isNotEmpty) {
+        Iterable<ShellRouteBase> shellRoutes = matchList.matches
+            .map((RouteMatch e) => e.route)
+            .whereType<ShellRouteBase>();
+        shellRoutes = RouteConfiguration.routesRecursively(shellRoutes)
+            .whereType<ShellRouteBase>();
+        _shellRouteState
+            .removeWhere((ShellRouteBase key, _) => !shellRoutes.contains(key));
+      }
     }
   }
 
@@ -273,12 +253,20 @@ class RouteBuilder {
         );
       }
 
-      final ShellRouteContext shellRouteContext = ShellRouteContext(
+      ShellRouteContext shellRouteContext = ShellRouteContext(
         subRoute: subRoute,
         routeMatchList: matchList,
+        shellRouteState: _shellRouteState[route],
         navigatorBuilder: buildShellNavigator,
       );
 
+      // Call the ShellRouteBase to create/update the shell route state
+      final Object? shellRouteState =
+          route.updateShellState(context, state, shellRouteContext);
+      _shellRouteState[route] = shellRouteState;
+      shellRouteContext =
+          shellRouteContext.copyWith(shellRouteState: shellRouteState);
+
       // Build the Page for this route
       final Page<Object?> page = _buildPageForRoute(
           context, state, match, pagePopContext,

packages/go_router/lib/src/configuration.dart

@@ -167,22 +167,23 @@ class RouteConfiguration {
     return true;
   }
 
-  static Iterable<RouteBase> _subRoutesRecursively(
-      List<RouteBase> routes) sync* {
+  /// Returns an Iterable that traverses the provided routes and their
+  /// sub-routes recursively.
+  static Iterable<RouteBase> routesRecursively(
+      Iterable<RouteBase> routes) sync* {
     for (final RouteBase route in routes) {
       yield route;
-      yield* _subRoutesRecursively(route.routes);
+      yield* routesRecursively(route.routes);
     }
   }
 
   static GoRoute? _findFirstGoRoute(List<RouteBase> routes) =>
-      _subRoutesRecursively(routes).whereType<GoRoute>().firstOrNull;
+      routesRecursively(routes).whereType<GoRoute>().firstOrNull;
 
   /// Tests if a route is a descendant of, or same as, an ancestor route.
   bool _debugIsDescendantOrSame(
           {required RouteBase ancestor, required RouteBase route}) =>
-      ancestor == route ||
-      _subRoutesRecursively(ancestor.routes).contains(route);
+      ancestor == route || routesRecursively(ancestor.routes).contains(route);
 
   /// Recursively traverses the routes of the provided StatefulShellBranch to
   /// find the first GoRoute, from which a full path will be derived.

packages/go_router/lib/src/matching.dart

@@ -154,20 +154,25 @@ class RouteMatchList {
 class UnmodifiableRouteMatchList {
   /// UnmodifiableRouteMatchList constructor.
   UnmodifiableRouteMatchList.from(RouteMatchList routeMatchList)
-      : _matches = List<RouteMatch>.unmodifiable(routeMatchList.matches),
-        _uri = routeMatchList.uri,
-        _pathParameters =
+      : matches = List<RouteMatch>.unmodifiable(routeMatchList.matches),
+        uri = routeMatchList.uri,
+        pathParameters =
             Map<String, String>.unmodifiable(routeMatchList.pathParameters);
 
-  final List<RouteMatch> _matches;
-  final Uri _uri;
-  final Map<String, String> _pathParameters;
+  /// The route matches.
+  final List<RouteMatch> matches;
+
+  /// The uri of the current match.
+  final Uri uri;
+
+  /// Parameters for the matched route, URI-encoded.
+  final Map<String, String> pathParameters;
 
   /// Creates a new [RouteMatchList] from this UnmodifiableRouteMatchList.
   RouteMatchList get modifiableMatchList => RouteMatchList(
-      List<RouteMatch>.from(_matches),
-      _uri,
-      Map<String, String>.from(_pathParameters));
+      List<RouteMatch>.from(matches),
+      uri,
+      Map<String, String>.from(pathParameters));
 
   @override
   bool operator ==(Object other) {
@@ -177,13 +182,13 @@ class UnmodifiableRouteMatchList {
     if (other is! UnmodifiableRouteMatchList) {
       return false;
     }
-    return listEquals<RouteMatch>(other._matches, _matches) &&
-        other._uri == _uri &&
-        mapEquals<String, String>(other._pathParameters, _pathParameters);
+    return listEquals<RouteMatch>(other.matches, matches) &&
+        other.uri == uri &&
+        mapEquals<String, String>(other.pathParameters, pathParameters);
   }
 
   @override
-  int get hashCode => Object.hash(_matches, _uri, _pathParameters);
+  int get hashCode => Object.hash(matches, uri, pathParameters);
 }
 
 /// An error that occurred during matching.

packages/go_router/lib/src/parser.dart

@@ -56,8 +56,12 @@ class GoRouteInformationParser extends RouteInformationParser<RouteMatchList> {
   ) {
     late final RouteMatchList initialMatches;
     try {
-      initialMatches = matcher.findMatch(routeInformation.location!,
-          extra: routeInformation.state);
+      if (routeInformation is PreParsedRouteInformation) {
+        initialMatches = routeInformation.matchlist;
+      } else {
+        initialMatches = matcher.findMatch(routeInformation.location!,
+            extra: routeInformation.state);
+      }
     } on MatcherError {
       log.info('No initial matches: ${routeInformation.location}');
 
@@ -124,3 +128,13 @@ class GoRouteInformationParser extends RouteInformationParser<RouteMatchList> {
     );
   }
 }
+
+/// Pre-parsed [RouteInformation] that contains a [RouteMatchList].
+class PreParsedRouteInformation extends RouteInformation {
+  /// Creates a [PreParsedRouteInformation].
+  PreParsedRouteInformation(
+      {super.location, super.state, required this.matchlist});
+
+  /// The pre-parsed [RouteMatchList].
+  final RouteMatchList matchlist;
+}