Nested Navigator state restoration predictive back examples (#153723)

I've updated these two examples to support state restoration of the navigation stack and verified that they work with predictive back in the tests. This was motivated by a worry that users are not properly setting up their navigation and that our examples are misleading them in the name of simplicity.

Author: justinmc

examples/api/lib/widgets/navigator_pop_handler/navigator_pop_handler.0.dart

@@ -16,10 +16,35 @@ class NavigatorPopHandlerApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
+      restorationScopeId: 'root',
       initialRoute: '/',
-      routes: <String, WidgetBuilder>{
-        '/': (BuildContext context) => _HomePage(),
-        '/nested_navigators': (BuildContext context) => const NestedNavigatorsPage(),
+      onGenerateRoute: (RouteSettings settings) {
+        return switch (settings.name) {
+          '/' => MaterialPageRoute<void>(
+            settings: const RouteSettings(
+              name: '/',
+            ),
+            builder: (BuildContext context) {
+              return _HomePage();
+            },
+          ),
+          '/nested_navigators' => MaterialPageRoute<void>(
+            settings: const RouteSettings(
+              name: '/nested_navigators',
+            ),
+            builder: (BuildContext context) {
+              return const _NestedNavigatorsPage();
+            },
+          ),
+          _ => MaterialPageRoute<void>(
+            settings: const RouteSettings(
+              name: 'unknown_page',
+            ),
+            builder: (BuildContext context) {
+              return const _UnknownPage();
+            },
+          ),
+        };
       },
     );
   }
@@ -43,7 +68,7 @@ class _HomePage extends StatelessWidget {
               title: const Text('Nested Navigator route'),
               subtitle: const Text('This route has another Navigator widget in addition to the one inside MaterialApp above.'),
               onTap: () {
-                Navigator.of(context).pushNamed('/nested_navigators');
+                Navigator.of(context).restorablePushNamed('/nested_navigators');
               },
             ),
           ],
@@ -53,14 +78,14 @@ class _HomePage extends StatelessWidget {
   }
 }
 
-class NestedNavigatorsPage extends StatefulWidget {
-  const NestedNavigatorsPage({super.key});
+class _NestedNavigatorsPage extends StatefulWidget {
+  const _NestedNavigatorsPage();
 
   @override
-  State<NestedNavigatorsPage> createState() => _NestedNavigatorsPageState();
+  State<_NestedNavigatorsPage> createState() => _NestedNavigatorsPageState();
 }
 
-class _NestedNavigatorsPageState extends State<NestedNavigatorsPage> {
+class _NestedNavigatorsPageState extends State<_NestedNavigatorsPage> {
   final GlobalKey<NavigatorState> _nestedNavigatorKey = GlobalKey<NavigatorState>();
 
   @override
@@ -71,36 +96,45 @@ class _NestedNavigatorsPageState extends State<NestedNavigatorsPage> {
       },
       child: Navigator(
         key: _nestedNavigatorKey,
+        restorationScopeId: 'nested-navigator',
         initialRoute: 'nested_navigators/one',
         onGenerateRoute: (RouteSettings settings) {
-          switch (settings.name) {
-            case 'nested_navigators/one':
-              final BuildContext rootContext = context;
-              return MaterialPageRoute<void>(
-                builder: (BuildContext context) => NestedNavigatorsPageOne(
-                  onBack: () {
-                    Navigator.of(rootContext).pop();
-                  },
-                ),
-              );
-            case 'nested_navigators/one/another_one':
-              return MaterialPageRoute<void>(
-                builder: (BuildContext context) => const NestedNavigatorsPageTwo(
-                ),
-              );
-            default:
-              throw Exception('Invalid route: ${settings.name}');
-          }
+          final BuildContext rootContext = context;
+          return switch (settings.name) {
+            'nested_navigators/one' => MaterialPageRoute<void>(
+              settings: const RouteSettings(
+                name: 'nested_navigators/one',
+              ),
+              builder: (BuildContext context) => _NestedNavigatorsPageOne(
+                onBack: () {
+                  Navigator.of(rootContext).pop();
+                },
+              ),
+            ),
+            'nested_navigators/one/another_one' => MaterialPageRoute<void>(
+              settings: const RouteSettings(
+                name: 'nested_navigators/one',
+              ),
+              builder: (BuildContext context) => const _NestedNavigatorsPageTwo(),
+            ),
+            _ => MaterialPageRoute<void>(
+              settings: const RouteSettings(
+                name: 'unknown_page',
+              ),
+              builder: (BuildContext context) {
+                return const _UnknownPage();
+              },
+            ),
+          };
         },
       ),
     );
   }
 }
 
-class NestedNavigatorsPageOne extends StatelessWidget {
-  const NestedNavigatorsPageOne({
+class _NestedNavigatorsPageOne extends StatelessWidget {
+  const _NestedNavigatorsPageOne({
     required this.onBack,
-    super.key,
   });
 
   final VoidCallback onBack;
@@ -117,7 +151,7 @@ class NestedNavigatorsPageOne extends StatelessWidget {
             const Text('A system back here returns to the home page.'),
             TextButton(
               onPressed: () {
-                Navigator.of(context).pushNamed('nested_navigators/one/another_one');
+                Navigator.of(context).restorablePushNamed('nested_navigators/one/another_one');
               },
               child: const Text('Go to another route in this nested Navigator'),
             ),
@@ -135,10 +169,8 @@ class NestedNavigatorsPageOne extends StatelessWidget {
   }
 }
 
-class NestedNavigatorsPageTwo extends StatelessWidget {
-  const NestedNavigatorsPageTwo({
-    super.key,
-  });
+class _NestedNavigatorsPageTwo extends StatelessWidget {
+  const _NestedNavigatorsPageTwo();
 
   @override
   Widget build(BuildContext context) {
@@ -162,3 +194,22 @@ class NestedNavigatorsPageTwo extends StatelessWidget {
     );
   }
 }
+
+class _UnknownPage extends StatelessWidget {
+  const _UnknownPage();
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      backgroundColor: Colors.grey.withBlue(180),
+      body: const Center(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: <Widget>[
+            Text('404'),
+          ],
+        ),
+      ),
+    );
+  }
+}