[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']!),
         ),
       ),
     ],

packages/go_router/example/lib/path_and_query_parameters.dart

@@ -9,9 +9,9 @@ import 'package:go_router/go_router.dart';
 //
 // The route segments that start with ':' are treated as path parameters when
 // defining GoRoute[s]. The parameter values can be accessed through
-// GoRouterState.params.
+// GoRouterState.pathParameters.
 //
-// The query parameters are automatically stored in GoRouterState.queryParams.
+// The query parameters are automatically stored in GoRouterState.queryParameters.
 
 /// Family data class.
 class Family {
@@ -84,8 +84,8 @@ class App extends StatelessWidget {
               path: 'family/:fid',
               builder: (BuildContext context, GoRouterState state) {
                 return FamilyScreen(
-                  fid: state.params['fid']!,
-                  asc: state.queryParams['sort'] == 'asc',
+                  fid: state.pathParameters['fid']!,
+                  asc: state.queryParameters['sort'] == 'asc',
                 );
               }),
         ],
@@ -149,7 +149,8 @@ class FamilyScreen extends StatelessWidget {
         actions: <Widget>[
           IconButton(
             onPressed: () => context.goNamed('family',
-                params: <String, String>{'fid': fid}, queryParams: newQueries),
+                pathParameters: <String, String>{'fid': fid},
+                queryParameters: newQueries),
             tooltip: 'sort ascending or descending',
             icon: const Icon(Icons.sort),
           )

packages/go_router/example/lib/redirection.dart

@@ -75,7 +75,7 @@ class App extends StatelessWidget {
     redirect: (BuildContext context, GoRouterState state) {
       // if the user is not logged in, they need to login
       final bool loggedIn = _loginInfo.loggedIn;
-      final bool loggingIn = state.subloc == '/login';
+      final bool loggingIn = state.matchedLocation == '/login';
       if (!loggedIn) {
         return '/login';
       }

packages/go_router/lib/fix_data.yaml

@@ -0,0 +1,151 @@
+# Copyright 2014 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.
+
+# For details regarding the *Flutter Fix* feature, see
+# https://flutter.dev/docs/development/tools/flutter-fix
+
+# Please add new fixes to the top of the file, separated by one blank line
+# from other fixes. In a comment, include a link to the PR where the change
+# requiring the fix was made.
+
+# Every fix must be tested. See the flutter/packages/flutter/test_fixes/README.md
+# file for instructions on testing these data driven fixes.
+
+# For documentation about this file format, see
+# https://dart.dev/go/data-driven-fixes
+
+version: 1
+transforms:
+  - title: "Replaces 'params' and 'queryParams' in 'GoRouter.replaceNamed' with `pathParameters` and `queryParameters`"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      method: 'replaceNamed'
+      inClass: 'GoRouter'
+    changes:
+      - kind: 'renameParameter'
+        oldName: 'params'
+        newName: 'pathParameters'
+      - kind: 'renameParameter'
+        oldName: 'queryParams'
+        newName: 'queryParameters'
+  - title: "Replaces 'params' and 'queryParams' in 'GoRouter.pushReplacementNamed' with `pathParameters` and `queryParameters`"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      method: 'pushReplacementNamed'
+      inClass: 'GoRouter'
+    changes:
+      - kind: 'renameParameter'
+        oldName: 'params'
+        newName: 'pathParameters'
+      - kind: 'renameParameter'
+        oldName: 'queryParams'
+        newName: 'queryParameters'
+
+  - title: "Replaces 'params' and 'queryParams' in 'GoRouter.pushNamed' with `pathParameters` and `queryParameters`"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      method: 'pushNamed'
+      inClass: 'GoRouter'
+    changes:
+      - kind: 'renameParameter'
+        oldName: 'params'
+        newName: 'pathParameters'
+      - kind: 'renameParameter'
+        oldName: 'queryParams'
+        newName: 'queryParameters'
+
+  - title: "Replaces 'params' and 'queryParams' in 'GoRouter.goNamed' with `pathParameters` and `queryParameters`"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      method: 'goNamed'
+      inClass: 'GoRouter'
+    changes:
+      - kind: 'renameParameter'
+        oldName: 'params'
+        newName: 'pathParameters'
+      - kind: 'renameParameter'
+        oldName: 'queryParams'
+        newName: 'queryParameters'
+
+  - title: "Replaces 'params' and 'queryParams' in 'GoRouter.namedLocation' with `pathParameters` and `queryParameters`"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      method: 'namedLocation'
+      inClass: 'GoRouter'
+    changes:
+      - kind: 'renameParameter'
+        oldName: 'params'
+        newName: 'pathParameters'
+      - kind: 'renameParameter'
+        oldName: 'queryParams'
+        newName: 'queryParameters'
+
+  - title: "Replaces 'params' and 'queryParams' in 'GoRouterState.namedLocation' with `pathParameters` and `queryParameters`"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      method: 'namedLocation'
+      inClass: 'GoRouterState'
+    changes:
+      - kind: 'renameParameter'
+        oldName: 'params'
+        newName: 'pathParameters'
+      - kind: 'renameParameter'
+        oldName: 'queryParams'
+        newName: 'queryParameters'
+
+  - title: "Replaces 'GoRouterState.queryParams' with 'GoRouterState.queryParameters'"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      field: 'queryParams'
+      inClass: 'GoRouterState'
+    changes:
+      - kind: 'rename'
+        newName: 'queryParameters'
+
+  - title: "Replaces 'GoRouterState.fullpath' with 'GoRouterState.fullPath'"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      field: 'fullpath'
+      inClass: 'GoRouterState'
+    changes:
+      - kind: 'rename'
+        newName: 'fullPath'
+
+  - title: "Replaces 'GoRouterState.params' with 'GoRouterState.pathParameters'"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      field: 'params'
+      inClass: 'GoRouterState'
+    changes:
+      - kind: 'rename'
+        newName: 'pathParameters'
+
+  - title: "Replaces 'GoRouterState.subloc' with 'GoRouterState.matchedLocation'"
+    date: 2023-04-24
+    bulkApply: true
+    element:
+      uris: [ 'go_router.dart' ]
+      field: 'subloc'
+      inClass: 'GoRouterState'
+    changes:
+      - kind: 'rename'
+        newName: 'matchedLocation'