[go_router] Add ShellRoute

packages/go_router/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 4.5.0
+
+- Adds ShellRoute for nested navigation support (flutter/flutter#99126)
+- Adds `parentNavigatorKey` to GoRoute, which specifies the Navigator to place that
+  route's Page onto.
+
 ## 4.4.1
 
 - Fix an issue where disabling logging clears the root logger's listeners

packages/go_router/README.md

@@ -134,6 +134,48 @@ methods:
 onTap: () => context.go('/page2')
 ```
 
+## Nested Navigation
+
+The `ShellRoute` route type provides a way to wrap all sub-routes with a UI shell.
+Under the hood, GoRouter places a Navigator in the widget tree, which is used
+to display matching sub-routes:
+
+```dart
+final  _router = GoRouter(
+  routes: [
+    ShellRoute(
+      builder: (context, state, child) {
+        return AppScaffold(child: child);
+      },
+      routes: <RouteBase>[
+        GoRoute(
+          path: '/albums',
+          builder: (context, state) {
+            return HomeScreen();
+          },
+          routes: <RouteBase>[
+            /// The details screen to display stacked on the inner Navigator.
+            GoRoute(
+              path: 'song/:songId',
+              builder: (BuildContext context, GoRouterState state) {
+                return const DetailsScreen(label: 'A');
+              },
+            ),
+          ],
+        ),
+      ],
+    ),
+  ],
+);
+```
+
+For more details, see the
+[ShellRoute](https://pub.dev/documentation/go_router/latest/go_router/ShellRoute-class.html)
+API documentation. For a complete
+example, see the 
+[ShellRoute sample](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/shell_route.dart)
+in the example/ directory.
+
 ### Still not sure how to proceed?
 See [examples](https://github.com/flutter/packages/tree/main/packages/go_router/example) for complete runnable examples or visit [API documentation](https://pub.dev/documentation/go_router/latest/go_router/go_router-library.html)
 

packages/go_router/example/lib/shell_route.dart

@@ -0,0 +1,236 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+
+final GlobalKey<NavigatorState> _rootNavigatorKey =
+    GlobalKey<NavigatorState>(debugLabel: 'root');
+final GlobalKey<NavigatorState> _shellNavigatorKey =
+    GlobalKey<NavigatorState>(debugLabel: 'shell');
+
+// This scenario demonstrates how to set up nested navigation using ShellRoute,
+// which is a pattern where an additional Navigator is placed in the widget tree
+// to be used instead of the root navigator. This allows deep-links to display
+// pages along with other UI components such as a BottomNavigationBar.
+//
+// This example demonstrates how to display a route within a ShellRoute and also
+// push a screen using a different navigator (such as the root Navigator) by
+// providing a `parentNavigatorKey`.
+
+void main() {
+  runApp(ShellRouteExampleApp());
+}
+
+/// An example demonstrating how to use [ShellRoute]
+class ShellRouteExampleApp extends StatelessWidget {
+  /// Creates a [ShellRouteExampleApp]
+  ShellRouteExampleApp({Key? key}) : super(key: key);
+
+  final GoRouter _router = GoRouter(
+    navigatorKey: _rootNavigatorKey,
+    initialLocation: '/a',
+    routes: <RouteBase>[
+      /// Application shell
+      ShellRoute(
+        navigatorKey: _shellNavigatorKey,
+        builder: (BuildContext context, GoRouterState state, Widget child) {
+          return ScaffoldWithNavBar(child: child);
+        },
+        routes: <RouteBase>[
+          /// The first screen to display in the bottom navigation bar.
+          GoRoute(
+            path: '/a',
+            builder: (BuildContext context, GoRouterState state) {
+              return const ScreenA();
+            },
+            routes: <RouteBase>[
+              // The details screen to display stacked on the inner Navigator.
+              // This will cover screen A but not the application shell.
+              GoRoute(
+                path: 'details',
+                builder: (BuildContext context, GoRouterState state) {
+                  return const DetailsScreen(label: 'A');
+                },
+              ),
+            ],
+          ),
+
+          /// Displayed when the second item in the the bottom navigation bar is
+          /// selected.
+          GoRoute(
+            path: '/b',
+            builder: (BuildContext context, GoRouterState state) {
+              return const ScreenB();
+            },
+            routes: <RouteBase>[
+              /// Same as "/a/details", but displayed on the root Navigator by
+              /// specifying [parentNavigatorKey]. This will cover both screen B
+              /// and the application shell.
+              GoRoute(
+                path: 'details',
+                parentNavigatorKey: _rootNavigatorKey,
+                builder: (BuildContext context, GoRouterState state) {
+                  return const DetailsScreen(label: 'B');
+                },
+              ),
+            ],
+          ),
+        ],
+      ),
+    ],
+  );
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(
+      title: 'Flutter Demo',
+      theme: ThemeData(
+        primarySwatch: Colors.blue,
+      ),
+      routeInformationParser: _router.routeInformationParser,
+      routerDelegate: _router.routerDelegate,
+      routeInformationProvider: _router.routeInformationProvider,
+    );
+  }
+}
+
+/// Builds the "shell" for the app by building a Scaffold with a
+/// BottomNavigationBar, where [child] is placed in the body of the Scaffold.
+class ScaffoldWithNavBar extends StatelessWidget {
+  /// Constructs an [ScaffoldWithNavBar].
+  const ScaffoldWithNavBar({
+    required this.child,
+    Key? key,
+  }) : super(key: key);
+
+  /// The widget to display in the body of the Scaffold.
+  /// In this sample, it is a Navigator.
+  final Widget child;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: child,
+      bottomNavigationBar: BottomNavigationBar(
+        items: const <BottomNavigationBarItem>[
+          BottomNavigationBarItem(
+            icon: Icon(Icons.home),
+            label: 'A Screen',
+          ),
+          BottomNavigationBarItem(
+            icon: Icon(Icons.business),
+            label: 'B Screen',
+          ),
+        ],
+        currentIndex: _calculateSelectedIndex(context),
+        onTap: (int idx) => _onItemTapped(idx, context),
+      ),
+    );
+  }
+
+  static int _calculateSelectedIndex(BuildContext context) {
+    final GoRouter route = GoRouter.of(context);
+    final String location = route.location;
+    if (location == '/a') {
+      return 0;
+    }
+    if (location == '/b') {
+      return 1;
+    }
+    return 0;
+  }
+
+  void _onItemTapped(int index, BuildContext context) {
+    switch (index) {
+      case 0:
+        GoRouter.of(context).go('/a');
+        break;
+      case 1:
+        GoRouter.of(context).go('/b');
+        break;
+    }
+  }
+}
+
+/// The first screen in the bottom navigation bar.
+class ScreenA extends StatelessWidget {
+  /// Constructs a [ScreenA] widget.
+  const ScreenA({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(),
+      body: Center(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: <Widget>[
+            const Text('Screen A'),
+            TextButton(
+              onPressed: () {
+                GoRouter.of(context).go('/a/details');
+              },
+              child: const Text('View A details'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+/// The second screen in the bottom navigation bar.
+class ScreenB extends StatelessWidget {
+  /// Constructs a [ScreenB] widget.
+  const ScreenB({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(),
+      body: Center(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: <Widget>[
+            const Text('Screen B'),
+            TextButton(
+              onPressed: () {
+                GoRouter.of(context).go('/b/details');
+              },
+              child: const Text('View B details'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+/// The details screen for either the A or B screen.
+class DetailsScreen extends StatelessWidget {
+  /// Constructs a [DetailsScreen].
+  const DetailsScreen({
+    required this.label,
+    Key? key,
+  }) : super(key: key);
+
+  /// The label to display in the center of the screen.
+  final String label;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Details Screen'),
+      ),
+      body: Center(
+        child: Text(
+          'Details for $label',
+          style: Theme.of(context).textTheme.headlineMedium,
+        ),
+      ),
+    );
+  }
+}

packages/go_router/lib/go_router.dart

@@ -6,7 +6,8 @@
 /// deep linking, data-driven routes and more.
 library go_router;
 
-export 'src/configuration.dart' show GoRoute, GoRouterState;
+export 'src/configuration.dart'
+    show GoRoute, GoRouterState, RouteBase, ShellRoute;
 export 'src/misc/extensions.dart';
 export 'src/misc/inherited_router.dart';
 export 'src/misc/refresh_stream.dart';