Return value when pop

packages/go_router/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 6.3.0
+
+- Supports for returning values on pop.
+
 ## NEXT
 
 - Updates compileSdkVersion to 33.

packages/go_router/doc/navigation.md

@@ -68,4 +68,21 @@ Navigator.of(context).push(
 );
 ```
 
+## Returning values
+Waiting for a value to be returned:
+
+```dart
+onTap: () {
+  final bool? result = await context.push<bool>('/page2');
+  if(result ?? false)...
+}
+```
+
+Returning a value:
+
+```dart
+onTap: () => context.pop(true)
+```
+
+
 [Named routes]: https://pub.dev/documentation/go_router/latest/topics/Named%20routes-topic.html

packages/go_router/lib/src/delegate.dart

@@ -76,15 +76,15 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
   }
 
   /// Pushes the given location onto the page stack
-  void push(RouteMatchList matches) {
+  Future<T?> push<T extends Object?>(RouteMatchList matches) async {
     assert(matches.last.route is! ShellRoute);
 
     // Remap the pageKey to allow any number of the same page on the stack
     final int count = (_pushCounts[matches.fullpath] ?? 0) + 1;
     _pushCounts[matches.fullpath] = count;
     final ValueKey<String> pageKey =
         ValueKey<String>('${matches.fullpath}-p$count');
-    final ImperativeRouteMatch newPageKeyMatch = ImperativeRouteMatch(
+    final ImperativeRouteMatch<T> newPageKeyMatch = ImperativeRouteMatch<T>(
       route: matches.last.route,
       subloc: matches.last.subloc,
       extra: matches.last.extra,
@@ -95,6 +95,7 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
 
     _matchList.push(newPageKeyMatch);
     notifyListeners();
+    return newPageKeyMatch.future;
   }
 
   /// Returns `true` if the active Navigator can pop.
@@ -113,6 +114,7 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
     final _NavigatorStateIterator iterator = _createNavigatorStateIterator();
     while (iterator.moveNext()) {
       if (iterator.current.canPop()) {
+        iterator.matchList.last.complete(result);
         iterator.current.pop<T>(result);
         return;
       }
@@ -268,8 +270,7 @@ class _NavigatorStateIterator extends Iterator<NavigatorState> {
 }
 
 /// The route match that represent route pushed through [GoRouter.push].
-// TODO(chunhtai): Removes this once imperative API no longer insert route match.
-class ImperativeRouteMatch extends RouteMatch {
+class ImperativeRouteMatch<T> extends RouteMatch {
   /// Constructor for [ImperativeRouteMatch].
   ImperativeRouteMatch({
     required super.route,
@@ -278,8 +279,25 @@ class ImperativeRouteMatch extends RouteMatch {
     required super.error,
     required super.pageKey,
     required this.matches,
-  });
+  }) : _completer = Completer<T?>();
 
   /// The matches that produces this route match.
   final RouteMatchList matches;
+
+  /// The completer for the promise returned by [GoRouter.push].
+  final Completer<T?> _completer;
+
+  /// Completes the promise returned by [GoRouter.push].
+  @override
+  void complete([dynamic value]) {
+    _completer.complete(value as T?);
+  }
+
+  /// Returns `true` if the promise returned by [GoRouter.push] has been completed.
+  @override
+  bool didComplete() => _completer.isCompleted;
+
+  /// The future of the [RouteMatch] completer. When the future completes, this
+  /// will return the value passed to [complete].
+  Future<T?> get future => _completer.future;
 }

packages/go_router/lib/src/match.dart

@@ -61,6 +61,29 @@ class RouteMatch {
     throw MatcherError('Unexpected route type: $route', restLoc);
   }
 
+  /// Completes the promise returned by [GoRouter.push], allowing comunication
+  /// between pages.
+  ///
+  /// If the promise has already been completed, this method does nothing.
+  ///
+  /// E.g.:
+  /// ```dart
+  /// final bool? result = await context.push<bool>('/page2');
+  /// if(result ?? false){
+  ///   // do something
+  /// }
+  /// ```
+  /// When the page is popped, the promise is completed with the value passed,
+  /// and the push method returns.
+  /// to [Navigator.pop].
+  /// ```dart
+  /// context.pop(true);
+  /// ```
+  void complete([dynamic value]) {}
+
+  /// Returns `true` if the promise returned by [GoRouter.push] has been completed.
+  bool? didComplete() => null;
+
   /// The matched route.
   final RouteBase route;
 

packages/go_router/lib/src/misc/extensions.dart

@@ -37,17 +37,17 @@ extension GoRouterHelper on BuildContext {
       );
 
   /// Push a location onto the page stack.
-  void push(String location, {Object? extra}) =>
+  Future<T?> push<T extends Object?>(String location, {Object? extra}) =>
       GoRouter.of(this).push(location, extra: extra);
 
   /// Navigate to a named route onto the page stack.
-  void pushNamed(
+  Future<T?> pushNamed<T extends Object?>(
     String name, {
     Map<String, String> params = const <String, String>{},
     Map<String, dynamic> queryParams = const <String, dynamic>{},
     Object? extra,
   }) =>
-      GoRouter.of(this).pushNamed(
+      GoRouter.of(this).pushNamed<T>(
         name,
         params: params,
         queryParams: queryParams,

packages/go_router/lib/src/parser.dart

@@ -104,7 +104,7 @@ class GoRouteInformationParser extends RouteInformationParser<RouteMatchList> {
     }
     if (configuration.matches.last is ImperativeRouteMatch) {
       configuration =
-          (configuration.matches.last as ImperativeRouteMatch).matches;
+          (configuration.matches.last as ImperativeRouteMatch<dynamic>).matches;
     }
     return RouteInformation(
       location: configuration.uri.toString(),

packages/go_router/lib/src/router.dart

@@ -151,7 +151,7 @@ class GoRouter extends ChangeNotifier implements RouterConfig<RouteMatchList> {
         routerDelegate.currentConfiguration.matches.last
             is ImperativeRouteMatch) {
       newLocation = (routerDelegate.currentConfiguration.matches.last
-              as ImperativeRouteMatch)
+              as ImperativeRouteMatch<dynamic>)
           .matches
           .uri
           .toString();
@@ -204,32 +204,30 @@ class GoRouter extends ChangeNotifier implements RouterConfig<RouteMatchList> {
 
   /// Push a URI location onto the page stack w/ optional query parameters, e.g.
   /// `/family/f2/person/p1?color=blue`
-  void push(String location, {Object? extra}) {
+  Future<T?> push<T extends Object?>(String location, {Object? extra}) async {
     assert(() {
       log.info('pushing $location');
       return true;
     }());
-    _routeInformationParser
-        .parseRouteInformationWithDependencies(
+    final RouteMatchList matches =
+        await _routeInformationParser.parseRouteInformationWithDependencies(
       RouteInformation(location: location, state: extra),
       // TODO(chunhtai): avoid accessing the context directly through global key.
       // https://github.com/flutter/flutter/issues/99112
       _routerDelegate.navigatorKey.currentContext!,
-    )
-        .then<void>((RouteMatchList matches) {
-      _routerDelegate.push(matches);
-    });
+    );
+    return _routerDelegate.push<T>(matches);
   }
 
   /// Push a named route onto the page stack w/ optional parameters, e.g.
   /// `name='person', params={'fid': 'f2', 'pid': 'p1'}`
-  void pushNamed(
+  Future<T?> pushNamed<T extends Object?>(
     String name, {
     Map<String, String> params = const <String, String>{},
     Map<String, dynamic> queryParams = const <String, dynamic>{},
     Object? extra,
   }) =>
-      push(
+      push<T>(
         namedLocation(name, params: params, queryParams: queryParams),
         extra: extra,
       );

packages/go_router/pubspec.yaml

@@ -1,7 +1,7 @@
 name: go_router
 description: A declarative router for Flutter based on Navigation 2 supporting
   deep linking, data-driven routes and more
-version: 6.2.0
+version: 6.3.0
 repository: https://github.com/flutter/packages/tree/main/packages/go_router
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+go_router%22
 

packages/go_router/test/delegate_test.dart

@@ -141,7 +141,7 @@ void main() {
         reason: 'The last match should have been removed',
       );
       expect(
-        (goRouter.routerDelegate.matches.last as ImperativeRouteMatch)
+        (goRouter.routerDelegate.matches.last as ImperativeRouteMatch<dynamic>)
             .matches
             .uri
             .toString(),

packages/go_router/test/go_router_test.dart

@@ -2396,8 +2396,8 @@ void main() {
       expect(router.location, loc);
       expect(matches.matches, hasLength(2));
       expect(find.byType(PersonScreen), findsOneWidget);
-      final ImperativeRouteMatch imperativeRouteMatch =
-          matches.matches.last as ImperativeRouteMatch;
+      final ImperativeRouteMatch<dynamic> imperativeRouteMatch =
+          matches.matches.last as ImperativeRouteMatch<dynamic>;
       expect(imperativeRouteMatch.matches.pathParameters['fid'], fid);
       expect(imperativeRouteMatch.matches.pathParameters['pid'], pid);
     });
@@ -2655,6 +2655,26 @@ void main() {
       expect(router.extra, extra);
     });
 
+    testWidgets('calls [push] on closest GoRouter with a promise',
+        (WidgetTester tester) async {
+      final GoRouterPushSpy router = GoRouterPushSpy(routes: routes);
+      await tester.pumpWidget(
+        MaterialApp.router(
+          routeInformationProvider: router.routeInformationProvider,
+          routeInformationParser: router.routeInformationParser,
+          routerDelegate: router.routerDelegate,
+          title: 'GoRouter Example',
+        ),
+      );
+      final String? result = await router.push<String>(
+        location,
+        extra: extra,
+      );
+      expect(result, extra);
+      expect(router.myLocation, location);
+      expect(router.extra, extra);
+    });
+
     testWidgets('calls [pushNamed] on closest GoRouter',
         (WidgetTester tester) async {
       final GoRouterPushNamedSpy router = GoRouterPushNamedSpy(routes: routes);
@@ -2676,6 +2696,30 @@ void main() {
       expect(router.extra, extra);
     });
 
+    testWidgets('calls [pushNamed] on closest GoRouter with a promise',
+        (WidgetTester tester) async {
+      final GoRouterPushNamedSpy router = GoRouterPushNamedSpy(routes: routes);
+      await tester.pumpWidget(
+        MaterialApp.router(
+          routeInformationProvider: router.routeInformationProvider,
+          routeInformationParser: router.routeInformationParser,
+          routerDelegate: router.routerDelegate,
+          title: 'GoRouter Example',
+        ),
+      );
+      final String? result = await router.pushNamed<String>(
+        name,
+        params: params,
+        queryParams: queryParams,
+        extra: extra,
+      );
+      expect(result, extra);
+      expect(router.extra, extra);
+      expect(router.name, name);
+      expect(router.params, params);
+      expect(router.queryParams, queryParams);
+    });
+
     testWidgets('calls [pop] on closest GoRouter', (WidgetTester tester) async {
       final GoRouterPopSpy router = GoRouterPopSpy(routes: routes);
       await tester.pumpWidget(

packages/go_router/test/inherited_test.dart

@@ -129,11 +129,12 @@ class MockGoRouter extends GoRouter {
   late String latestPushedName;
 
   @override
-  void pushNamed(String name,
+  Future<T?> pushNamed<T extends Object?>(String name,
       {Map<String, String> params = const <String, String>{},
       Map<String, dynamic> queryParams = const <String, dynamic>{},
       Object? extra}) {
     latestPushedName = name;
+    return Future<T?>.value();
   }
 
   @override

packages/go_router/test/test_helpers.dart

@@ -95,9 +95,10 @@ class GoRouterPushSpy extends GoRouter {
   Object? extra;
 
   @override
-  void push(String location, {Object? extra}) {
+  Future<T?> push<T extends Object?>(String location, {Object? extra}) {
     myLocation = location;
     this.extra = extra;
+    return Future<T?>.value(extra as T?);
   }
 }
 
@@ -110,7 +111,7 @@ class GoRouterPushNamedSpy extends GoRouter {
   Object? extra;
 
   @override
-  void pushNamed(
+  Future<T?> pushNamed<T extends Object?>(
     String name, {
     Map<String, String> params = const <String, String>{},
     Map<String, dynamic> queryParams = const <String, dynamic>{},
@@ -120,6 +121,7 @@ class GoRouterPushNamedSpy extends GoRouter {
     this.params = params;
     this.queryParams = queryParams;
     this.extra = extra;
+    return Future<T?>.value(extra as T?);
   }
 }