[go_router] Add support for preloading branches of StatefulShellRoute (revised solution)

packages/go_router/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 13.3.0
+
+- Adds preload support to StatefulShellRoute, configurable via `preload` parameter on StatefulShellBranch.
+
 ## 13.2.2
 
 - Fixes restoreRouteInformation issue when GoRouter.optionURLReflectsImperativeAPIs is true and the last match is ShellRouteMatch

packages/go_router/example/lib/others/custom_stateful_shell_route.dart

@@ -10,6 +10,12 @@ final GlobalKey<NavigatorState> _rootNavigatorKey =
     GlobalKey<NavigatorState>(debugLabel: 'root');
 final GlobalKey<NavigatorState> _tabANavigatorKey =
     GlobalKey<NavigatorState>(debugLabel: 'tabANav');
+final GlobalKey<NavigatorState> _tabBNavigatorKey =
+    GlobalKey<NavigatorState>(debugLabel: 'tabBNav');
+final GlobalKey<NavigatorState> _tabB1NavigatorKey =
+    GlobalKey<NavigatorState>(debugLabel: 'tabB1Nav');
+final GlobalKey<NavigatorState> _tabB2NavigatorKey =
+    GlobalKey<NavigatorState>(debugLabel: 'tabB2Nav');
 
 // This example demonstrates how to setup nested navigation using a
 // BottomNavigationBar, where each bar item uses its own persistent navigator,
@@ -80,71 +86,69 @@ class NestedTabNavigationExampleApp extends StatelessWidget {
 
           // The route branch for the third tab of the bottom navigation bar.
           StatefulShellBranch(
+            navigatorKey: _tabBNavigatorKey,
+            // To enable preloading of the initial locations of branches, pass
+            // 'true' for the parameter preload.
+            preload: true,
             // StatefulShellBranch will automatically use the first descendant
             // GoRoute as the initial location of the branch. If another route
             // is desired, specify the location of it using the defaultLocation
             // parameter.
-            // defaultLocation: '/c2',
+            // defaultLocation: '/b1',
             routes: <RouteBase>[
-              StatefulShellRoute(
+              StatefulShellRoute.indexedStack(
                 builder: (BuildContext context, GoRouterState state,
                     StatefulNavigationShell navigationShell) {
-                  // Just like with the top level StatefulShellRoute, no
-                  // customization is done in the builder function.
-                  return navigationShell;
+                  return TabbedRootScreen(navigationShell: navigationShell);
                 },
-                navigatorContainerBuilder: (BuildContext context,
-                    StatefulNavigationShell navigationShell,
-                    List<Widget> children) {
-                  // Returning a customized container for the branch
-                  // Navigators (i.e. the `List<Widget> children` argument).
-                  //
-                  // See TabbedRootScreen for more details on how the children
-                  // are managed (in a TabBarView).
-                  return TabbedRootScreen(
-                      navigationShell: navigationShell, children: children);
-                },
-                // This bottom tab uses a nested shell, wrapping sub routes in a
-                // top TabBar.
                 branches: <StatefulShellBranch>[
-                  StatefulShellBranch(routes: <GoRoute>[
-                    GoRoute(
-                      path: '/b1',
-                      builder: (BuildContext context, GoRouterState state) =>
-                          const TabScreen(
-                              label: 'B1', detailsPath: '/b1/details'),
-                      routes: <RouteBase>[
+                  StatefulShellBranch(
+                      navigatorKey: _tabB1NavigatorKey,
+                      routes: <GoRoute>[
                         GoRoute(
-                          path: 'details',
+                          path: '/b1',
                           builder:
                               (BuildContext context, GoRouterState state) =>
-                                  const DetailsScreen(
-                            label: 'B1',
-                            withScaffold: false,
-                          ),
+                                  const TabScreen(
+                                      label: 'B1', detailsPath: '/b1/details'),
+                          routes: <RouteBase>[
+                            GoRoute(
+                              path: 'details',
+                              builder:
+                                  (BuildContext context, GoRouterState state) =>
+                                      const DetailsScreen(
+                                label: 'B1',
+                                withScaffold: false,
+                              ),
+                            ),
+                          ],
                         ),
-                      ],
-                    ),
-                  ]),
-                  StatefulShellBranch(routes: <GoRoute>[
-                    GoRoute(
-                      path: '/b2',
-                      builder: (BuildContext context, GoRouterState state) =>
-                          const TabScreen(
-                              label: 'B2', detailsPath: '/b2/details'),
-                      routes: <RouteBase>[
+                      ]),
+                  StatefulShellBranch(
+                      navigatorKey: _tabB2NavigatorKey,
+                      // To enable preloading for all nested branches, set
+                      // preload to 'true'.
+                      preload: true,
+                      routes: <GoRoute>[
                         GoRoute(
-                          path: 'details',
+                          path: '/b2',
                           builder:
                               (BuildContext context, GoRouterState state) =>
-                                  const DetailsScreen(
-                            label: 'B2',
-                            withScaffold: false,
-                          ),
+                                  const TabScreen(
+                                      label: 'B2', detailsPath: '/b2/details'),
+                          routes: <RouteBase>[
+                            GoRoute(
+                              path: 'details',
+                              builder:
+                                  (BuildContext context, GoRouterState state) =>
+                                      const DetailsScreen(
+                                label: 'B2',
+                                withScaffold: false,
+                              ),
+                            ),
+                          ],
                         ),
-                      ],
-                    ),
-                  ]),
+                      ]),
                 ],
               ),
             ],
@@ -376,23 +380,20 @@ class DetailsScreenState extends State<DetailsScreen> {
 /// Builds a nested shell using a [TabBar] and [TabBarView].
 class TabbedRootScreen extends StatefulWidget {
   /// Constructs a TabbedRootScreen
-  const TabbedRootScreen(
-      {required this.navigationShell, required this.children, super.key});
+  const TabbedRootScreen({required this.navigationShell, super.key});
 
   /// The current state of the parent StatefulShellRoute.
   final StatefulNavigationShell navigationShell;
 
-  /// The children (branch Navigators) to display in the [TabBarView].
-  final List<Widget> children;
-
   @override
   State<StatefulWidget> createState() => _TabbedRootScreenState();
 }
 
 class _TabbedRootScreenState extends State<TabbedRootScreen>
     with SingleTickerProviderStateMixin {
+  late final int branchCount = widget.navigationShell.route.branches.length;
   late final TabController _tabController = TabController(
-      length: widget.children.length,
+      length: branchCount,
       vsync: this,
       initialIndex: widget.navigationShell.currentIndex);
 
@@ -404,9 +405,9 @@ class _TabbedRootScreenState extends State<TabbedRootScreen>
 
   @override
   Widget build(BuildContext context) {
-    final List<Tab> tabs = widget.children
-        .mapIndexed((int i, _) => Tab(text: 'Tab ${i + 1}'))
-        .toList();
+    final List<Tab> tabs =
+        List<Tab>.generate(branchCount, (int i) => Tab(text: 'Tab ${i + 1}'))
+            .toList();
 
     return Scaffold(
       appBar: AppBar(
@@ -416,10 +417,7 @@ class _TabbedRootScreenState extends State<TabbedRootScreen>
             tabs: tabs,
             onTap: (int tappedIndex) => _onTabTap(context, tappedIndex),
           )),
-      body: TabBarView(
-        controller: _tabController,
-        children: widget.children,
-      ),
+      body: widget.navigationShell,
     );
   }
 
@@ -441,6 +439,11 @@ 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 ('/b1')
+    debugPrint('Building TabScreen - $label');
+
     return Center(
       child: Column(
         mainAxisSize: MainAxisSize.min,

packages/go_router/example/lib/stateful_shell_route.dart

@@ -60,6 +60,9 @@ class NestedTabNavigationExampleApp extends StatelessWidget {
                 ],
               ),
             ],
+            // To enable preloading of the initial locations of branches, pass
+            // 'true' for the parameter preload.
+            // preload: true,
           ),
 
           // The route branch for the second tab of the bottom navigation bar.

packages/go_router/lib/src/builder.dart

@@ -270,16 +270,22 @@ class _CustomNavigatorState extends State<_CustomNavigator> {
       route: match.route,
       routerState: state,
       navigatorKey: navigatorKey,
+      match: match,
       routeMatchList: widget.matchList,
-      navigatorBuilder:
-          (List<NavigatorObserver>? observers, String? restorationScopeId) {
+      navigatorBuilder: (
+        GlobalKey<NavigatorState> navigatorKey,
+        ShellRouteMatch match,
+        RouteMatchList matchList,
+        List<NavigatorObserver>? observers,
+        String? restorationScopeId,
+      ) {
         return _CustomNavigator(
           // The state needs to persist across rebuild.
           key: GlobalObjectKey(navigatorKey.hashCode),
           navigatorRestorationId: restorationScopeId,
           navigatorKey: navigatorKey,
           matches: match.matches,
-          matchList: widget.matchList,
+          matchList: matchList,
           configuration: widget.configuration,
           observers: observers ?? const <NavigatorObserver>[],
           onPopPageWithRouteMatch: widget.onPopPageWithRouteMatch,

packages/go_router/lib/src/route.dart

@@ -57,7 +57,13 @@ typedef StatefulShellRoutePageBuilder = Page<dynamic> Function(
 
 /// Signature for functions used to build Navigators
 typedef NavigatorBuilder = Widget Function(
-    List<NavigatorObserver>? observers, String? restorationScopeId);
+    GlobalKey<NavigatorState> navigatorKey,
+    ShellRouteMatch match,
+    RouteMatchList matchList,
+    List<NavigatorObserver>? observers,
+    String? restorationScopeId);
+// typedef NavigatorBuilder = Widget Function(
+//     List<NavigatorObserver>? observers, String? restorationScopeId);
 
 /// Signature for function used in [RouteBase.onExit].
 ///
@@ -502,6 +508,7 @@ class ShellRouteContext {
     required this.route,
     required this.routerState,
     required this.navigatorKey,
+    required this.match,
     required this.routeMatchList,
     required this.navigatorBuilder,
   });
@@ -516,12 +523,22 @@ class ShellRouteContext {
   /// [route].
   final GlobalKey<NavigatorState> navigatorKey;
 
+  /// The `ShellRouteMatch` in [routeMatchList] that corresponds to the
+  /// associated shell route.
+  final ShellRouteMatch match;
+
   /// The route match list representing the current location within the
   /// associated shell route.
   final RouteMatchList routeMatchList;
 
   /// Function used to build the [Navigator] for the current route.
   final NavigatorBuilder navigatorBuilder;
+
+  Widget _buildNavigatorForCurrentRoute(
+      List<NavigatorObserver>? observers, String? restorationScopeId) {
+    return navigatorBuilder(
+        navigatorKey, match, routeMatchList, observers, restorationScopeId);
+  }
 }
 
 /// A route that displays a UI shell around the matching child route.
@@ -659,8 +676,8 @@ class ShellRoute extends ShellRouteBase {
   Widget? buildWidget(BuildContext context, GoRouterState state,
       ShellRouteContext shellRouteContext) {
     if (builder != null) {
-      final Widget navigator =
-          shellRouteContext.navigatorBuilder(observers, restorationScopeId);
+      final Widget navigator = shellRouteContext._buildNavigatorForCurrentRoute(
+          observers, restorationScopeId);
       return builder!(context, state, navigator);
     }
     return null;
@@ -670,8 +687,8 @@ class ShellRoute extends ShellRouteBase {
   Page<dynamic>? buildPage(BuildContext context, GoRouterState state,
       ShellRouteContext shellRouteContext) {
     if (pageBuilder != null) {
-      final Widget navigator =
-          shellRouteContext.navigatorBuilder(observers, restorationScopeId);
+      final Widget navigator = shellRouteContext._buildNavigatorForCurrentRoute(
+          observers, restorationScopeId);
       return pageBuilder!(context, state, navigator);
     }
     return null;
@@ -988,6 +1005,7 @@ class StatefulShellBranch {
     this.initialLocation,
     this.restorationScopeId,
     this.observers,
+    this.preload = false,
   }) : navigatorKey = navigatorKey ?? GlobalKey<NavigatorState>() {
     assert(() {
       ShellRouteBase._debugCheckSubRouteParentNavigatorKeys(
@@ -1024,6 +1042,22 @@ class StatefulShellBranch {
   /// The observers parameter is used by the [Navigator] built for this branch.
   final List<NavigatorObserver>? observers;
 
+  /// Whether this route branch should be loaded only when navigating to it for
+  /// the first time (the default behavior, i.e. 'false'), or if it should be
+  /// eagerly loaded (preloaded).
+  ///
+  /// If this property is true, the branch will be loaded immediately when the
+  /// associated [StatefulShellRoute] is visited for the first time. In that
+  /// case, the branch will be preloaded by navigating to the initial location
+  /// (see [initialLocation]).
+  ///
+  /// *Note:* The primary purpose of branch preloading is to enhance the user
+  /// experience when switching branches, which might for instance involve
+  /// preparing the UI for animated transitions etc. Care must be taken to
+  /// **keep the preloading to an absolute minimum** to avoid any unnecessary
+  /// resource use.
+  final bool preload;
+
   /// The default route of this branch, i.e. the first descendant [GoRoute].
   ///
   /// This route will be used when loading the branch for the first time, if
@@ -1172,6 +1206,9 @@ class StatefulNavigationShellState extends State<StatefulNavigationShell>
   final Map<StatefulShellBranch, _RestorableRouteMatchList> _branchLocations =
       <StatefulShellBranch, _RestorableRouteMatchList>{};
 
+  bool _isBranchLoaded(StatefulShellBranch branch) =>
+      _branchNavigators[branch.navigatorKey] != null;
+
   @override
   String? get restorationId => route.restorationScopeId;
 
@@ -1226,6 +1263,8 @@ class StatefulNavigationShellState extends State<StatefulNavigationShell>
   }
 
   void _updateCurrentBranchStateFromWidget() {
+    _preloadBranches();
+
     final StatefulShellBranch branch = route.branches[widget.currentIndex];
     final ShellRouteContext shellRouteContext = widget.shellRouteContext;
     final RouteMatchList currentBranchLocation =
@@ -1242,8 +1281,40 @@ class StatefulNavigationShellState extends State<StatefulNavigationShell>
     final bool locationChanged =
         previousBranchLocation != currentBranchLocation;
     if (locationChanged || !hasExistingNavigator) {
-      _branchNavigators[branch.navigatorKey] = shellRouteContext
-          .navigatorBuilder(branch.observers, branch.restorationScopeId);
+      _branchNavigators[branch.navigatorKey] =
+          shellRouteContext._buildNavigatorForCurrentRoute(
+              branch.observers, branch.restorationScopeId);
+    }
+  }
+
+  void _preloadBranches() {
+    for (int i = 0; i < route.branches.length; i++) {
+      final StatefulShellBranch branch = route.branches[i];
+      if (i != widget.currentIndex &&
+          branch.preload &&
+          !_isBranchLoaded(branch)) {
+        final RouteMatchList matchList = _router.configuration
+            .findMatch(widget._effectiveInitialBranchLocation(i));
+
+        ShellRouteMatch? match;
+        matchList.visitRouteMatches((RouteMatchBase e) {
+          if (e is ShellRouteMatch && e.route == widget.route) {
+            match = e;
+            return false;
+          }
+          return true;
+        });
+
+        final Widget navigator = widget.shellRouteContext.navigatorBuilder(
+            branch.navigatorKey,
+            match!,
+            matchList,
+            branch.observers,
+            branch.restorationScopeId);
+
+        _branchLocation(branch, false).value = matchList;
+        _branchNavigators[branch.navigatorKey] = navigator;
+      }
     }
   }