[go_router_builder]: Add support for relative routes (#9749)

Adds support for TypedRelativeGoRoute.

Builds on #9732

Continuation of #8476 by @ThangVuNguyenViet

Compared to #8476, the approach taken in this PR avoids breaking changes and creates a separate RouteData subclass instead of extending GoRouteData. The approach increases flexibility and avoids extending behavior that might not make sense for a relative route.

Fully resolves flutter/flutter#108177.

## Pre-Review Checklist

**Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: LukasMirbt

packages/go_router_builder/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 3.3.0
+
+- Adds support for `TypedRelativeGoRoute`.
+
 ## 3.2.1
 
 - Changes generated whitespace for better compatibility with new Dart formatter.

packages/go_router_builder/README.md

@@ -8,12 +8,12 @@ To use `go_router_builder`, you need to have the following dependencies in
 ```yaml
 dependencies:
   # ...along with your other dependencies
-  go_router: ^16.0.0
+  go_router: ^16.2.0
 
 dev_dependencies:
   # ...along with your other dev-dependencies
   build_runner: ^2.6.0
-  go_router_builder: ^3.1.0
+  go_router_builder: ^3.3.0
 ```
 
 ### Source code
@@ -455,6 +455,32 @@ class MyGoRouteData extends GoRouteData with _$MyGoRouteData {
 
 An example is available [here](https://github.com/flutter/packages/blob/main/packages/go_router_builder/example/lib/shell_route_with_keys_example.dart).
 
+## Relative routes
+
+Relative routes allow reusing the same `RouteData` in different parts of the route tree.
+Define a relative route by extending `RelativeGoRouteData`.
+
+<?code-excerpt "example/lib/readme_excerpts.dart (relativeRoute)"?>
+```dart
+@TypedRelativeGoRoute<DetailsRoute>(path: 'details')
+class DetailsRoute extends RelativeGoRouteData with _$DetailsRoute {
+  const DetailsRoute();
+
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      const DetailsScreen();
+}
+```
+
+Navigate using the `goRelative` or `pushRelative` methods provided by the code generator:
+
+<?code-excerpt "example/lib/readme_excerpts.dart (goRelative)"?>
+```dart
+void onTapRelative() => const DetailsRoute().goRelative(context);
+```
+
+Relative routing methods are not idempotent and will cause an error when the relative location does not match a route.
+
 ## Run tests
 
 To run unit tests, run command `dart tool/run_tests.dart` from `packages/go_router_builder/`.

packages/go_router_builder/example/lib/go_relative.dart

@@ -0,0 +1,187 @@
+// 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.
+
+// ignore_for_file: public_member_api_docs, unreachable_from_main
+
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+
+part 'go_relative.g.dart';
+
+void main() => runApp(const MyApp());
+
+/// The main app.
+class MyApp extends StatelessWidget {
+  /// Constructs a [MyApp]
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(routerConfig: _router);
+  }
+}
+
+/// The route configuration.
+final GoRouter _router = GoRouter(routes: $appRoutes);
+const TypedRelativeGoRoute<DetailsRoute> detailRoute =
+    TypedRelativeGoRoute<DetailsRoute>(
+      path: 'details/:detailId',
+      routes: <TypedRoute<RouteData>>[
+        TypedRelativeGoRoute<SettingsRoute>(path: 'settings/:settingId'),
+      ],
+    );
+
+@TypedGoRoute<HomeRoute>(
+  path: '/',
+  routes: <TypedRoute<RouteData>>[
+    TypedGoRoute<DashboardRoute>(
+      path: '/dashboard',
+      routes: <TypedRoute<RouteData>>[detailRoute],
+    ),
+    detailRoute,
+  ],
+)
+class HomeRoute extends GoRouteData with _$HomeRoute {
+  @override
+  Widget build(BuildContext context, GoRouterState state) {
+    return const HomeScreen();
+  }
+}
+
+class DashboardRoute extends GoRouteData with _$DashboardRoute {
+  @override
+  Widget build(BuildContext context, GoRouterState state) {
+    return const DashboardScreen();
+  }
+}
+
+class DetailsRoute extends RelativeGoRouteData with _$DetailsRoute {
+  const DetailsRoute({required this.detailId});
+  final String detailId;
+
+  @override
+  Widget build(BuildContext context, GoRouterState state) {
+    return DetailsScreen(id: detailId);
+  }
+}
+
+class SettingsRoute extends RelativeGoRouteData with _$SettingsRoute {
+  const SettingsRoute({required this.settingId});
+  final String settingId;
+
+  @override
+  Widget build(BuildContext context, GoRouterState state) {
+    return SettingsScreen(id: settingId);
+  }
+}
+
+/// The home screen
+class HomeScreen extends StatelessWidget {
+  /// Constructs a [HomeScreen]
+  const HomeScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('Home Screen')),
+      body: Column(
+        mainAxisAlignment: MainAxisAlignment.center,
+        children: <Widget>[
+          ElevatedButton(
+            onPressed: () {
+              const DetailsRoute(detailId: 'DetailsId').goRelative(context);
+            },
+            child: const Text('Go to the Details screen'),
+          ),
+          ElevatedButton(
+            onPressed: () {
+              DashboardRoute().go(context);
+            },
+            child: const Text('Go to the Dashboard screen'),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+/// The home screen
+class DashboardScreen extends StatelessWidget {
+  /// Constructs a [DashboardScreen]
+  const DashboardScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('Dashboard Screen')),
+      body: Column(
+        children: <Widget>[
+          ElevatedButton(
+            onPressed: () {
+              const DetailsRoute(detailId: 'DetailsId').goRelative(context);
+            },
+            child: const Text('Go to the Details screen'),
+          ),
+          ElevatedButton(
+            onPressed: () => context.pop(),
+            child: const Text('Go back'),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+/// The details screen
+class DetailsScreen extends StatelessWidget {
+  /// Constructs a [DetailsScreen]
+  const DetailsScreen({super.key, required this.id});
+
+  final String id;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: Text('Details Screen $id')),
+      body: Center(
+        child: Column(
+          children: <Widget>[
+            ElevatedButton(
+              onPressed: () => context.pop(),
+              child: const Text('Go back'),
+            ),
+            ElevatedButton(
+              onPressed:
+                  () => const SettingsRoute(
+                    settingId: 'SettingsId',
+                  ).goRelative(context),
+              child: const Text('Go to the Settings screen'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+/// The details screen
+class SettingsScreen extends StatelessWidget {
+  /// Constructs a [SettingsScreen]
+  const SettingsScreen({super.key, required this.id});
+
+  final String id;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: Text('Settings Screen $id')),
+      body: Center(
+        child: TextButton(
+          onPressed: () => context.pop(),
+          child: const Text('Go back'),
+        ),
+      ),
+    );
+  }
+}