[go_router] Add ShellRoute

[johnpryan]

Adds ShellRoute

Resolves flutter/flutter#108141

[prince-kumar]

LGTM

[johnpryan]

@loic-sharma @chunhtai ready for another look - I added some functionality to ShellRoute with some tests, but right now this is still a "dark" feature and not part of the public API exposed by lib/go_router.dart.

[johnpryan]

After discussing this offline, I want to make some changes to this PR:

• Remove NestedStackRoute
• Remove StackedRoute and stick with GoRoute
• ShellRoute now always builds a Router and Navigator. This means that sub-routes will stack on this Navigator by default, rather than requiring a NestedNavigatorRoute. We will use an additional Router to ensure that we are handling back button behavior correctly. This cannot be made optional because pageBuilder would break for child routes of ShellRoute.
• Add a navigatorKey parameter to the GoRoute constructor. This specifies which Navigator to place this GoRoute onto. By default, GoRoutes stack onto the Navigator built by the nearest ShellRoute ancestor.
• Add a shellNavigatorKey parameter to the ShellRoute constructor. This specifies the navigator key to use when building the Navigator associated with this ShellRoute.
• Add a navigatorKey parameter to the ShellRoute constructor, which has the same behavior as navigatorKey on GoRoute.

[loic-sharma]

Should this PR target the go_router_v5 branch now?

[johnpryan]

Should this PR target the go_router_v5 branch now?

This isn't a breaking change, but maybe we should if we want to avoid merge conflicts. @chunhtai WDYT?

[cedvdb]

I assume this pr deals with nested routers.

One annoying thing with nested routers in practice are all the overlays like dialogs, bottom sheet, etc.

By default the result will be unexpected for most users: the modal barrier will only appear on the nested route. You have to explicitely call useRoot: true or something like that.

How will those scenarios be handled ?

I said it before when @chunhtai requested feedback: those two concepts of "overlay" and navigation should not have been mixed together in my opinion. Imo a separate overlay handler class is needed, but that might be to big of a change.

[johnpryan]

By default the result will be unexpected for most users: the modal barrier will only appear on the nested route. You have to explicitly call useRoot: true or something like that.
How will those scenarios be handled ?

You can specify which Navigator a route's screen will be overlaid on by specifying a navigatorKey on the GoRouter constructor or a shellNavigatorKey on the ShellRoute if you are using nested navigation. Then you specify the same navigatorKey on the GoRoute.

I said it before when @chunhtai requested feedback: those two concepts of "overlay" and navigation should not have been mixed together in my opinion. Imo a separate overlay handler class is needed, but that might be too big of a change.

Can you describe this scenario a bit more? This PR is a simplified version of go_router_prototype, which supports overlay-based navigation (GoRoute / StackedRoute) and shell-based navigation (ShellRoute). Shell-based navigation is very similar to how routing works for web-application frameworks and isn't based on overlays.

[johnpryan]

@cedvdb this is getting off-topic, would you mind filing a separate issue?

[johnpryan]

New pull request: #2453