[go_router] Expose Navigator clipBehavior on ShellRoute and StatefulShellBranch

[m1roxx]

The Navigator that ShellRoute and each StatefulShellBranch build always clipped its contents, with no way to opt out. A sub-route could therefore not paint outside the bounds the shell lays out for it — a box shadow or an overflowing menu gets cut off (see the samples in the issue).

This adds a clipBehavior parameter to ShellRoute and StatefulShellBranch that is forwarded to the Navigator each of them builds, as suggested by @chunhtai in flutter/flutter#131836 (comment).

It defaults to Clip.hardEdge, which is Navigator's own default, so existing behavior is unchanged. As noted in the issue discussion, setting Clip.none also lets route transition animations paint outside the shell's bounds; that trade-off is documented on the new clipBehavior doc comment so callers can make an informed choice.

StatefulShellBranch carries the parameter rather than StatefulShellRoute because each branch builds its own Navigator, which is how observers and restorationScopeId are already configured.

Fixes flutter/flutter#131836

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

Footnotes

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. ↩ ↩²

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request adds a clipBehavior property to ShellRoute and StatefulShellBranch in go_router, which is forwarded to the nested Navigator to control whether sub-routes can paint outside the shell's bounds. The feedback suggests specifying the default value Clip.hardEdge directly in the NavigatorBuilder typedef to ensure that custom or mock implementations can statically resolve the default value correctly.

[gemini-code-assist]

In the NavigatorBuilder typedef, the newly added optional named parameter clipBehavior is non-nullable but does not have a default value specified. Although the implementation in builder.dart provides a default value, it is highly recommended to specify the default value Clip.hardEdge directly in the typedef as well. This ensures that any caller of NavigatorBuilder (such as custom or mock implementations in tests) can statically resolve the default value correctly without relying on the implementation details.

Suggested change

	String? restorationScopeId, {
	Clip clipBehavior,
	});
	String? restorationScopeId, {
	Clip clipBehavior = Clip.hardEdge,
	});

[m1roxx]

@googlebot I signed it!