Add RelativeGoRouteData and TypedRelativeGoRoute

Author: LukasMirbt

packages/go_router/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 16.0.1
+
+- Adds `RelativeGoRouteData` and `TypedRelativeGoRoute`.
+
 ## 16.0.0
 
 - **BREAKING CHANGE**

packages/go_router/lib/src/route_data.dart

@@ -134,7 +134,7 @@ abstract class GoRouteData extends RouteData {
     'GoRouteState to GoRouteData expando',
   );
 
-  /// The location of this route.
+  /// The location of this route, e.g. /family/f2/person/p1
   String get location => throw _shouldBeGeneratedError;
 
   /// Navigate to the route.
@@ -159,6 +159,151 @@ abstract class GoRouteData extends RouteData {
       );
 }
 
+/// A class to represent a relative [GoRoute] in
+/// [Type-safe routing](https://pub.dev/documentation/go_router/latest/topics/Type-safe%20routes-topic.html).
+///
+/// Subclasses must override one of [build], [buildPage], or
+/// [redirect].
+/// {@category Type-safe routes}
+abstract class RelativeGoRouteData extends RouteData {
+  /// Allows subclasses to have `const` constructors.
+  ///
+  /// [RelativeGoRouteData] is abstract and cannot be instantiated directly.
+  const RelativeGoRouteData();
+
+  /// Creates the [Widget] for `this` route.
+  ///
+  /// Subclasses must override one of [build], [buildPage], or
+  /// [redirect].
+  ///
+  /// Corresponds to [GoRoute.builder].
+  Widget build(BuildContext context, GoRouterState state) =>
+      throw UnimplementedError(
+        'One of `build` or `buildPage` must be implemented.',
+      );
+
+  /// A page builder for this route.
+  ///
+  /// Subclasses can override this function to provide a custom [Page].
+  ///
+  /// Subclasses must override one of [build], [buildPage] or
+  /// [redirect].
+  ///
+  /// Corresponds to [GoRoute.pageBuilder].
+  ///
+  /// By default, returns a [Page] instance that is ignored, causing a default
+  /// [Page] implementation to be used with the results of [build].
+  Page<void> buildPage(BuildContext context, GoRouterState state) =>
+      const NoOpPage();
+
+  /// An optional redirect function for this route.
+  ///
+  /// Subclasses must override one of [build], [buildPage], or
+  /// [redirect].
+  ///
+  /// Corresponds to [GoRoute.redirect].
+  FutureOr<String?> redirect(BuildContext context, GoRouterState state) => null;
+
+  /// Called when this route is removed from GoRouter's route history.
+  ///
+  /// Corresponds to [GoRoute.onExit].
+  FutureOr<bool> onExit(BuildContext context, GoRouterState state) => true;
+
+  /// A helper function used by generated code.
+  ///
+  /// Should not be used directly.
+  static String $location(String path, {Map<String, dynamic>? queryParams}) =>
+      Uri.parse(path)
+          .replace(
+            queryParameters:
+                // Avoid `?` in generated location if `queryParams` is empty
+                queryParams?.isNotEmpty ?? false ? queryParams : null,
+          )
+          .toString();
+
+  /// A helper function used by generated code.
+  ///
+  /// Should not be used directly.
+  static GoRoute $route<T extends RelativeGoRouteData>({
+    required String path,
+    bool caseSensitive = true,
+    required T Function(GoRouterState) factory,
+    GlobalKey<NavigatorState>? parentNavigatorKey,
+    List<RouteBase> routes = const <RouteBase>[],
+  }) {
+    T factoryImpl(GoRouterState state) {
+      final Object? extra = state.extra;
+
+      // If the "extra" value is of type `T` then we know it's the source
+      // instance of `RelativeGoRouteData`, so it doesn't need to be recreated.
+      if (extra is T) {
+        return extra;
+      }
+
+      return (_stateObjectExpando[state] ??= factory(state)) as T;
+    }
+
+    Widget builder(BuildContext context, GoRouterState state) =>
+        factoryImpl(state).build(context, state);
+
+    Page<void> pageBuilder(BuildContext context, GoRouterState state) =>
+        factoryImpl(state).buildPage(context, state);
+
+    FutureOr<String?> redirect(BuildContext context, GoRouterState state) =>
+        factoryImpl(state).redirect(context, state);
+
+    FutureOr<bool> onExit(BuildContext context, GoRouterState state) =>
+        factoryImpl(state).onExit(context, state);
+
+    return GoRoute(
+      path: path,
+      caseSensitive: caseSensitive,
+      builder: builder,
+      pageBuilder: pageBuilder,
+      redirect: redirect,
+      routes: routes,
+      parentNavigatorKey: parentNavigatorKey,
+      onExit: onExit,
+    );
+  }
+
+  /// Used to cache [RelativeGoRouteData] that corresponds to a given [GoRouterState]
+  /// to minimize the number of times it has to be deserialized.
+  static final Expando<RelativeGoRouteData> _stateObjectExpando =
+      Expando<RelativeGoRouteData>(
+    'GoRouteState to RelativeGoRouteData expando',
+  );
+
+  /// The location of this route, e.g. person/p1
+  String get location => throw _shouldBeGeneratedError;
+
+  /// The relative location of this route, e.g. ./person/p1
+  String get relativeLocation => throw _shouldBeGeneratedError;
+
+  /// Navigate to the route.
+  void goRelative(BuildContext context) => throw _shouldBeGeneratedError;
+
+  /// Push the route onto the page stack.
+  Future<T?> pushRelative<T>(BuildContext context) =>
+      throw _shouldBeGeneratedError;
+
+  /// Replaces the top-most page of the page stack with the route.
+  void pushReplacementRelative(BuildContext context) =>
+      throw _shouldBeGeneratedError;
+
+  /// Replaces the top-most page of the page stack with the route but treats
+  /// it as the same page.
+  ///
+  /// The page key will be reused. This will preserve the state and not run any
+  /// page animation.
+  ///
+  void replaceRelative(BuildContext context) => throw _shouldBeGeneratedError;
+
+  static UnimplementedError get _shouldBeGeneratedError => UnimplementedError(
+        'Should be generated using [Type-safe routing](https://pub.dev/documentation/go_router/latest/topics/Type-safe%20routes-topic.html).',
+      );
+}
+
 /// A class to represent a [ShellRoute] in
 /// [Type-safe routing](https://pub.dev/documentation/go_router/latest/topics/Type-safe%20routes-topic.html).
 abstract class ShellRouteData extends RouteData {
@@ -430,6 +575,41 @@ class TypedGoRoute<T extends GoRouteData> extends TypedRoute<T> {
   final bool caseSensitive;
 }
 
+/// A superclass for each typed relative go route descendant
+@Target(<TargetKind>{TargetKind.library, TargetKind.classType})
+class TypedRelativeGoRoute<T extends RelativeGoRouteData>
+    extends TypedRoute<T> {
+  /// Default const constructor
+  const TypedRelativeGoRoute({
+    required this.path,
+    this.routes = const <TypedRoute<RouteData>>[],
+    this.caseSensitive = true,
+  });
+
+  /// The relative path that corresponds to this route.
+  ///
+  /// See [GoRoute.path].
+  ///
+  ///
+  final String path;
+
+  /// Child route definitions.
+  ///
+  /// See [RouteBase.routes].
+  final List<TypedRoute<RouteData>> routes;
+
+  /// Determines whether the route matching is case sensitive.
+  ///
+  /// When `true`, the path must match the specified case. For example,
+  /// a route with `path: '/family/:fid'` will not match `/FaMiLy/f2`.
+  ///
+  /// When `false`, the path matching is case insensitive.  The route
+  /// with `path: '/family/:fid'` will match `/FaMiLy/f2`.
+  ///
+  /// Defaults to `true`.
+  final bool caseSensitive;
+}
+
 /// A superclass for each typed shell route descendant
 @Target(<TargetKind>{TargetKind.library, TargetKind.classType})
 class TypedShellRoute<T extends ShellRouteData> extends TypedRoute<T> {

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: 16.0.0
+version: 16.0.1
 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