[go_router] Cleans up route match API and introduces dart fix (#3819)

Clean up API around RouteMatch/RouteMatchList/GoRouterState,

This is a breaking change that renamed some of the GoRouterState property to have a more descriptive name as flutter style guide suggested https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#avoid-abbreviations

also introducing dart fix to help with migration

Author: chunhtai

packages/go_router/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 7.0.0
+
+- **BREAKING CHANGE**:
+  - For the below changes, run `dart fix --apply` to automatically migrate your code.
+    - `GoRouteState.subloc` has been renamed to `GoRouteState.matchedLocation`.
+    - `GoRouteState.params` has been renamed to `GoRouteState.pathParameters`.
+    - `GoRouteState.fullpath` has been renamed to `GoRouteState.fullPath`.
+    - `GoRouteState.queryParams` has been renamed to `GoRouteState.queryParameters`.
+    - `params` and `queryParams` in `GoRouteState.namedLocation` have been renamed to `pathParameters` and `queryParameters`.
+    - `params` and `queryParams` in `GoRouter`'s `namedLocation`, `pushNamed`, `pushReplacementNamed`
+      `replaceNamed` have been renamed to `pathParameters` and `queryParameters`.
+  - For the below changes, please follow the [migration guide](https://docs.google.com/document/d/10Xbpifbs4E-zh6YE5akIO8raJq_m3FIXs6nUGdOspOg).
+    - `params` and `queryParams` in `BuildContext`'s `namedLocation`, `pushNamed`, `pushReplacementNamed`
+      `replaceNamed` have been renamed to `pathParameters` and `queryParameters`.
+- Cleans up API and makes RouteMatchList immutable.
+
 ## 6.5.9
 
 - Removes navigator keys from `GoRouteData` and `ShellRouteData`.

packages/go_router/README.md

@@ -37,6 +37,7 @@ See the API documentation for details on the following topics:
 - [Error handling](https://pub.dev/documentation/go_router/latest/topics/Error%20handling-topic.html)
 
 ## Migration guides
+- [Migrating to 7.0.0](https://docs.google.com/document/d/10Xbpifbs4E-zh6YE5akIO8raJq_m3FIXs6nUGdOspOg).
 - [Migrating to 6.0.0](https://flutter.dev/go/go-router-v6-breaking-changes)
 - [Migrating to 5.1.2](https://flutter.dev/go/go-router-v5-1-2-breaking-changes)
 - [Migrating to 5.0](https://flutter.dev/go/go-router-v5-breaking-changes)

packages/go_router/analysis_options.yaml

@@ -0,0 +1,5 @@
+include: ../../analysis_options.yaml
+
+analyzer:
+  exclude:
+    - "test_fixes/**"

packages/go_router/doc/configuration.md

@@ -43,7 +43,7 @@ the builder callback:
 ```dart
 GoRoute(
   path: '/users/:userId',
-  builder: (context, state) => const UserScreen(id: state.params['userId']),
+  builder: (context, state) => const UserScreen(id: state.pathParameters['userId']),
 ),
 ```
 
@@ -55,7 +55,7 @@ after the `?`), use [GoRouterState][]. For example, a URL path such as
 ```dart
 GoRoute(
   path: '/users',
-  builder: (context, state) => const UsersScreen(filter: state.queryParams['filter']),
+  builder: (context, state) => const UsersScreen(filter: state.queryParameters['filter']),
 ),
 ```
 

packages/go_router/doc/named-routes.md

@@ -14,7 +14,7 @@ To navigate to a route using its name, call [`goNamed`](https://pub.dev/document
 ```dart
 TextButton(
   onPressed: () {
-    context.goNamed('song', params: {'songId': 123});
+    context.goNamed('song', pathParameters: {'songId': 123});
   },
   child: const Text('Go to song 2'),
 ),
@@ -25,7 +25,7 @@ Alternatively, you can look up the location for a name using `namedLocation`:
 ```dart
 TextButton(
   onPressed: () {
-    final String location = context.namedLocation('song', params: {'songId': 123});
+    final String location = context.namedLocation('song', pathParameters: {'songId': 123});
     context.go(location);
   },
   child: const Text('Go to song 2'),

packages/go_router/example/lib/async_redirection.dart

@@ -55,7 +55,7 @@ class App extends StatelessWidget {
       // cause go_router to reparse current route if StreamAuth has new sign-in
       // information.
       final bool loggedIn = await StreamAuthScope.of(context).isSignedIn();
-      final bool loggingIn = state.subloc == '/login';
+      final bool loggingIn = state.matchedLocation == '/login';
       if (!loggedIn) {
         return '/login';
       }

packages/go_router/example/lib/books/main.dart

@@ -63,7 +63,7 @@ class Bookstore extends StatelessWidget {
       GoRoute(
         path: '/book/:bookId',
         redirect: (BuildContext context, GoRouterState state) =>
-            '/books/all/${state.params['bookId']}',
+            '/books/all/${state.pathParameters['bookId']}',
       ),
       GoRoute(
         path: '/books/:kind(new|all|popular)',
@@ -72,14 +72,14 @@ class Bookstore extends StatelessWidget {
           key: _scaffoldKey,
           child: BookstoreScaffold(
             selectedTab: ScaffoldTab.books,
-            child: BooksScreen(state.params['kind']!),
+            child: BooksScreen(state.pathParameters['kind']!),
           ),
         ),
         routes: <GoRoute>[
           GoRoute(
             path: ':bookId',
             builder: (BuildContext context, GoRouterState state) {
-              final String bookId = state.params['bookId']!;
+              final String bookId = state.pathParameters['bookId']!;
               final Book? selectedBook = libraryInstance.allBooks
                   .firstWhereOrNull((Book b) => b.id.toString() == bookId);
 
@@ -91,7 +91,7 @@ class Bookstore extends StatelessWidget {
       GoRoute(
         path: '/author/:authorId',
         redirect: (BuildContext context, GoRouterState state) =>
-            '/authors/${state.params['authorId']}',
+            '/authors/${state.pathParameters['authorId']}',
       ),
       GoRoute(
         path: '/authors',
@@ -107,7 +107,7 @@ class Bookstore extends StatelessWidget {
           GoRoute(
             path: ':authorId',
             builder: (BuildContext context, GoRouterState state) {
-              final int authorId = int.parse(state.params['authorId']!);
+              final int authorId = int.parse(state.pathParameters['authorId']!);
               final Author? selectedAuthor = libraryInstance.allAuthors
                   .firstWhereOrNull((Author a) => a.id == authorId);
 
@@ -135,7 +135,7 @@ class Bookstore extends StatelessWidget {
 
   String? _guard(BuildContext context, GoRouterState state) {
     final bool signedIn = _auth.signedIn;
-    final bool signingIn = state.subloc == '/signin';
+    final bool signingIn = state.matchedLocation == '/signin';
 
     // Go to /signin if the user is not signed in
     if (!signedIn && !signingIn) {

packages/go_router/example/lib/named_routes.dart

@@ -84,14 +84,15 @@ class App extends StatelessWidget {
             name: 'family',
             path: 'family/:fid',
             builder: (BuildContext context, GoRouterState state) =>
-                FamilyScreen(fid: state.params['fid']!),
+                FamilyScreen(fid: state.pathParameters['fid']!),
             routes: <GoRoute>[
               GoRoute(
                 name: 'person',
                 path: 'person/:pid',
                 builder: (BuildContext context, GoRouterState state) {
                   return PersonScreen(
-                      fid: state.params['fid']!, pid: state.params['pid']!);
+                      fid: state.pathParameters['fid']!,
+                      pid: state.pathParameters['pid']!);
                 },
               ),
             ],
@@ -119,7 +120,7 @@ class HomeScreen extends StatelessWidget {
             ListTile(
               title: Text(entry.value.name),
               onTap: () => context.go(context.namedLocation('family',
-                  params: <String, String>{'fid': entry.key})),
+                  pathParameters: <String, String>{'fid': entry.key})),
             )
         ],
       ),
@@ -147,8 +148,8 @@ class FamilyScreen extends StatelessWidget {
               title: Text(entry.value.name),
               onTap: () => context.go(context.namedLocation(
                 'person',
-                params: <String, String>{'fid': fid, 'pid': entry.key},
-                queryParams: <String, String>{'qid': 'quid'},
+                pathParameters: <String, String>{'fid': fid, 'pid': entry.key},
+                queryParameters: <String, String>{'qid': 'quid'},
               )),
             ),
         ],

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

@@ -108,8 +108,8 @@ class Page1Screen extends StatelessWidget {
               ElevatedButton(
                 onPressed: () => context.goNamed(
                   'page2',
-                  params: <String, String>{'p1': 'pv1'},
-                  queryParams: <String, String>{'q1': 'qv1'},
+                  pathParameters: <String, String>{'p1': 'pv1'},
+                  queryParameters: <String, String>{'q1': 'qv1'},
                 ),
                 child: const Text('Go to page 2'),
               ),
@@ -134,7 +134,7 @@ class Page2Screen extends StatelessWidget {
               ElevatedButton(
                 onPressed: () => context.goNamed(
                   'page3',
-                  params: <String, String>{'p1': 'pv2'},
+                  pathParameters: <String, String>{'p1': 'pv2'},
                 ),
                 child: const Text('Go to page 3'),
               ),

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

@@ -32,7 +32,7 @@ class App extends StatelessWidget {
         path: '/page2',
         builder: (BuildContext context, GoRouterState state) =>
             Page2ScreenWithPush(
-          int.parse(state.queryParams['push-count']!),
+          int.parse(state.queryParameters['push-count']!),
         ),
       ),
     ],