Skip to content

Commit 738f6e5

Browse files
authored
[go_router] Expose Navigator clipBehavior on ShellRoute and StatefulShellBranch (flutter#12646)
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#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#131836 ## Pre-Review Checklist [^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.
1 parent ff3771f commit 738f6e5

5 files changed

Lines changed: 270 additions & 0 deletions

File tree

‎packages/go_router/lib/src/builder.dart‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,28 @@ typedef _ErrorBuilderForAppType = Widget Function(BuildContext context, GoRouter
4141
typedef PopPageWithRouteMatchCallback =
4242
bool Function(Route<dynamic> route, dynamic result, RouteMatchBase match);
4343

44+
/// The clip behavior of the [Navigator] identified by [navigatorKey].
45+
///
46+
/// A [ShellRoute] builds a single Navigator and carries the clip behavior
47+
/// itself, while a [StatefulShellRoute] builds one per branch, so the branch
48+
/// owning [navigatorKey] carries it. [ShellRouteBase] cannot be subclassed
49+
/// outside of this library, so those are the only two cases.
50+
Clip _clipBehaviorFor(ShellRouteBase route, GlobalKey<NavigatorState> navigatorKey) {
51+
switch (route) {
52+
case ShellRoute():
53+
return route.clipBehavior;
54+
case StatefulShellRoute():
55+
for (final StatefulShellBranch branch in route.branches) {
56+
if (branch.navigatorKey == navigatorKey) {
57+
return branch.clipBehavior;
58+
}
59+
}
60+
return Clip.hardEdge;
61+
default:
62+
return Clip.hardEdge;
63+
}
64+
}
65+
4466
/// Builds the top-level Navigator for GoRouter.
4567
class RouteBuilder {
4668
/// [RouteBuilder] constructor.
@@ -138,6 +160,7 @@ class _CustomNavigator extends StatefulWidget {
138160
required this.errorPageBuilder,
139161
required this.requestFocus,
140162
this.isShellNavigator = false,
163+
this.clipBehavior = Clip.hardEdge,
141164
});
142165

143166
final GlobalKey<NavigatorState> navigatorKey;
@@ -171,6 +194,11 @@ class _CustomNavigator extends StatefulWidget {
171194
final GoRouterPageBuilder? errorPageBuilder;
172195
final bool requestFocus;
173196

197+
/// The clip behavior of the [Navigator] built by this widget.
198+
///
199+
/// {@macro go_router.ShellRoute.clipBehavior}
200+
final Clip clipBehavior;
201+
174202
@override
175203
State<StatefulWidget> createState() => _CustomNavigatorState();
176204
}
@@ -330,6 +358,7 @@ class _CustomNavigatorState extends State<_CustomNavigator> {
330358
errorPageBuilder: widget.errorPageBuilder,
331359
requestFocus: widget.requestFocus,
332360
isShellNavigator: true,
361+
clipBehavior: _clipBehaviorFor(match.route, navigatorKey),
333362
),
334363
);
335364
},
@@ -465,6 +494,7 @@ class _CustomNavigatorState extends State<_CustomNavigator> {
465494
pages: _pages!,
466495
observers: widget.observers,
467496
onPopPage: _handlePopPage,
497+
clipBehavior: widget.clipBehavior,
468498
);
469499
return GoRouterStateRegistryScope(
470500
registry: _registry,

‎packages/go_router/lib/src/route.dart‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -728,6 +728,7 @@ class ShellRoute extends ShellRouteBase {
728728
super.parentNavigatorKey,
729729
GlobalKey<NavigatorState>? navigatorKey,
730730
this.restorationScopeId,
731+
this.clipBehavior = Clip.hardEdge,
731732
}) : assert(routes.isNotEmpty),
732733
navigatorKey = navigatorKey ?? GlobalKey<NavigatorState>(),
733734
super._() {
@@ -804,6 +805,20 @@ class ShellRoute extends ShellRouteBase {
804805
/// its history.
805806
final String? restorationScopeId;
806807

808+
/// The clip behavior of the [Navigator] built for this route.
809+
///
810+
/// {@template go_router.ShellRoute.clipBehavior}
811+
/// The nested Navigator clips its contents by default, so that the route
812+
/// transitions of its sub-routes are not painted outside the bounds the
813+
/// shell lays out for them. Set this to [Clip.none] when a sub-route needs
814+
/// to paint outside those bounds, for example to render a box shadow or an
815+
/// overflowing menu. Note that this also allows route transition animations
816+
/// to paint outside the bounds of the shell.
817+
///
818+
/// Defaults to [Clip.hardEdge].
819+
/// {@endtemplate}
820+
final Clip clipBehavior;
821+
807822
@override
808823
GlobalKey<NavigatorState> navigatorKeyForSubRoute(RouteBase subRoute) {
809824
assert(routes.contains(subRoute));
@@ -814,6 +829,7 @@ class ShellRoute extends ShellRouteBase {
814829
void debugFillProperties(DiagnosticPropertiesBuilder properties) {
815830
super.debugFillProperties(properties);
816831
properties.add(DiagnosticsProperty<GlobalKey<NavigatorState>>('navigatorKey', navigatorKey));
832+
properties.add(EnumProperty<Clip>('clipBehavior', clipBehavior, defaultValue: Clip.hardEdge));
817833
}
818834
}
819835

@@ -1127,6 +1143,7 @@ class StatefulShellBranch {
11271143
this.restorationScopeId,
11281144
this.observers,
11291145
this.preload = false,
1146+
this.clipBehavior = Clip.hardEdge,
11301147
}) : navigatorKey = navigatorKey ?? GlobalKey<NavigatorState>() {
11311148
assert(() {
11321149
ShellRouteBase._debugCheckSubRouteParentNavigatorKeys(routes, this.navigatorKey);
@@ -1162,6 +1179,14 @@ class StatefulShellBranch {
11621179
/// The observers parameter is used by the [Navigator] built for this branch.
11631180
final List<NavigatorObserver>? observers;
11641181

1182+
/// The clip behavior of the [Navigator] built for this branch.
1183+
///
1184+
/// Each branch of a [StatefulShellRoute] builds its own [Navigator], so the
1185+
/// clip behavior is configured per branch rather than on the shell route.
1186+
///
1187+
/// {@macro go_router.ShellRoute.clipBehavior}
1188+
final Clip clipBehavior;
1189+
11651190
/// Whether this route branch should be eagerly loaded when navigating to the
11661191
/// associated StatefulShellRoute for the first time.
11671192
///

‎packages/go_router/lib/src/route_data.dart‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,7 @@ abstract class ShellRouteData extends RouteData {
306306
bool notifyRootObserver = true,
307307
List<NavigatorObserver>? observers,
308308
String? restorationScopeId,
309+
Clip clipBehavior = Clip.hardEdge,
309310
}) {
310311
T factoryImpl(GoRouterState state) {
311312
return (_stateObjectExpando[state] ??= factory(state)) as T;
@@ -330,6 +331,7 @@ abstract class ShellRouteData extends RouteData {
330331
observers: observers,
331332
restorationScopeId: restorationScopeId,
332333
redirect: redirect,
334+
clipBehavior: clipBehavior,
333335
);
334336
}
335337

@@ -440,6 +442,7 @@ abstract class StatefulShellBranchData {
440442
String? initialLocation,
441443
String? restorationScopeId,
442444
bool preload = false,
445+
Clip clipBehavior = Clip.hardEdge,
443446
}) {
444447
return StatefulShellBranch(
445448
routes: routes,
@@ -448,6 +451,7 @@ abstract class StatefulShellBranchData {
448451
initialLocation: initialLocation,
449452
restorationScopeId: restorationScopeId,
450453
preload: preload,
454+
clipBehavior: clipBehavior,
451455
);
452456
}
453457
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds `clipBehavior` to `ShellRoute` and `StatefulShellBranch`, forwarded to the nested `Navigator`.
3+
version: minor
Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter/foundation.dart';
6+
import 'package:flutter_test/flutter_test.dart';
7+
import 'package:go_router/go_router.dart';
8+
import 'package:material_ui/material_ui.dart';
9+
10+
import 'test_helpers.dart';
11+
12+
/// Reads the clip behavior of the [Navigator] identified by [navigatorKey].
13+
///
14+
/// Offstage widgets are included so that the Navigators of inactive
15+
/// [StatefulShellBranch]es can be inspected too.
16+
Clip clipBehaviorOf(WidgetTester tester, GlobalKey<NavigatorState> navigatorKey) =>
17+
tester.widget<Navigator>(find.byKey(navigatorKey, skipOffstage: false)).clipBehavior;
18+
19+
class _ShellRouteData extends ShellRouteData {
20+
const _ShellRouteData();
21+
22+
@override
23+
Widget builder(BuildContext context, GoRouterState state, Widget navigator) => navigator;
24+
}
25+
26+
/// Reads the description of the `clipBehavior` diagnostics property of the
27+
/// given [route], or null if the property is hidden at its default value.
28+
String? clipBehaviorDiagnosticOf(ShellRoute route) {
29+
final builder = DiagnosticPropertiesBuilder();
30+
route.debugFillProperties(builder);
31+
return builder.properties
32+
.where((DiagnosticsNode node) => !node.isFiltered(DiagnosticLevel.info))
33+
.where((DiagnosticsNode node) => node.name == 'clipBehavior')
34+
.map((DiagnosticsNode node) => node.toDescription())
35+
.firstOrNull;
36+
}
37+
38+
void main() {
39+
group('ShellRoute', () {
40+
test('includes a non-default clipBehavior in debugFillProperties', () {
41+
ShellRoute shellRoute({Clip clipBehavior = Clip.hardEdge}) => ShellRoute(
42+
clipBehavior: clipBehavior,
43+
builder: (_, _, Widget child) => child,
44+
routes: <RouteBase>[GoRoute(path: '/', builder: (_, _) => const Text('Home'))],
45+
);
46+
47+
expect(clipBehaviorDiagnosticOf(shellRoute()), isNull);
48+
expect(clipBehaviorDiagnosticOf(shellRoute(clipBehavior: Clip.none)), 'none');
49+
});
50+
51+
testWidgets('clips the nested Navigator by default', (WidgetTester tester) async {
52+
final navigatorKey = GlobalKey<NavigatorState>(debugLabel: 'shell');
53+
await createRouter(<RouteBase>[
54+
ShellRoute(
55+
navigatorKey: navigatorKey,
56+
builder: (_, _, Widget child) => child,
57+
routes: <RouteBase>[GoRoute(path: '/', builder: (_, _) => const Text('Home'))],
58+
),
59+
], tester);
60+
61+
expect(clipBehaviorOf(tester, navigatorKey), Clip.hardEdge);
62+
});
63+
64+
testWidgets('forwards clipBehavior to the nested Navigator', (WidgetTester tester) async {
65+
final navigatorKey = GlobalKey<NavigatorState>(debugLabel: 'shell');
66+
await createRouter(<RouteBase>[
67+
ShellRoute(
68+
navigatorKey: navigatorKey,
69+
clipBehavior: Clip.none,
70+
builder: (_, _, Widget child) => child,
71+
routes: <RouteBase>[GoRoute(path: '/', builder: (_, _) => const Text('Home'))],
72+
),
73+
], tester);
74+
75+
expect(clipBehaviorOf(tester, navigatorKey), Clip.none);
76+
});
77+
78+
testWidgets('forwards clipBehavior to the nested Navigator when using pageBuilder', (
79+
WidgetTester tester,
80+
) async {
81+
final navigatorKey = GlobalKey<NavigatorState>(debugLabel: 'shell');
82+
await createRouter(<RouteBase>[
83+
ShellRoute(
84+
navigatorKey: navigatorKey,
85+
clipBehavior: Clip.antiAlias,
86+
pageBuilder: (_, _, Widget child) => MaterialPage<void>(child: child),
87+
routes: <RouteBase>[GoRoute(path: '/', builder: (_, _) => const Text('Home'))],
88+
),
89+
], tester);
90+
91+
expect(clipBehaviorOf(tester, navigatorKey), Clip.antiAlias);
92+
});
93+
});
94+
95+
group('StatefulShellBranch', () {
96+
testWidgets('clips the branch Navigator by default', (WidgetTester tester) async {
97+
final navigatorKey = GlobalKey<NavigatorState>(debugLabel: 'branch');
98+
await createRouter(<RouteBase>[
99+
StatefulShellRoute.indexedStack(
100+
builder: (_, _, StatefulNavigationShell shell) => shell,
101+
branches: <StatefulShellBranch>[
102+
StatefulShellBranch(
103+
navigatorKey: navigatorKey,
104+
routes: <RouteBase>[GoRoute(path: '/', builder: (_, _) => const Text('A'))],
105+
),
106+
],
107+
),
108+
], tester);
109+
110+
expect(clipBehaviorOf(tester, navigatorKey), Clip.hardEdge);
111+
});
112+
113+
testWidgets('forwards clipBehavior per branch', (WidgetTester tester) async {
114+
final keyA = GlobalKey<NavigatorState>(debugLabel: 'a');
115+
final keyB = GlobalKey<NavigatorState>(debugLabel: 'b');
116+
final root = GlobalKey<NavigatorState>(debugLabel: 'root');
117+
await createRouter(
118+
<RouteBase>[
119+
StatefulShellRoute.indexedStack(
120+
builder: (_, _, StatefulNavigationShell shell) => shell,
121+
branches: <StatefulShellBranch>[
122+
StatefulShellBranch(
123+
navigatorKey: keyA,
124+
clipBehavior: Clip.none,
125+
routes: <RouteBase>[GoRoute(path: '/a', builder: (_, _) => const Text('A'))],
126+
),
127+
StatefulShellBranch(
128+
navigatorKey: keyB,
129+
routes: <RouteBase>[GoRoute(path: '/b', builder: (_, _) => const Text('B'))],
130+
),
131+
],
132+
),
133+
],
134+
tester,
135+
navigatorKey: root,
136+
initialLocation: '/a',
137+
);
138+
139+
expect(clipBehaviorOf(tester, keyA), Clip.none);
140+
141+
root.currentContext!.go('/b');
142+
await tester.pumpAndSettle();
143+
144+
// Each branch keeps its own clip behavior; the loaded branches stay in
145+
// the tree because StatefulShellRoute preserves their state.
146+
expect(clipBehaviorOf(tester, keyA), Clip.none);
147+
expect(clipBehaviorOf(tester, keyB), Clip.hardEdge);
148+
});
149+
150+
testWidgets('forwards clipBehavior to preloaded branches', (WidgetTester tester) async {
151+
final keyA = GlobalKey<NavigatorState>(debugLabel: 'a');
152+
final keyB = GlobalKey<NavigatorState>(debugLabel: 'b');
153+
await createRouter(
154+
<RouteBase>[
155+
StatefulShellRoute.indexedStack(
156+
builder: (_, _, StatefulNavigationShell shell) => shell,
157+
branches: <StatefulShellBranch>[
158+
StatefulShellBranch(
159+
navigatorKey: keyA,
160+
routes: <RouteBase>[GoRoute(path: '/a', builder: (_, _) => const Text('A'))],
161+
),
162+
StatefulShellBranch(
163+
navigatorKey: keyB,
164+
preload: true,
165+
clipBehavior: Clip.none,
166+
routes: <RouteBase>[GoRoute(path: '/b', builder: (_, _) => const Text('B'))],
167+
),
168+
],
169+
),
170+
],
171+
tester,
172+
initialLocation: '/a',
173+
);
174+
await tester.pumpAndSettle();
175+
176+
expect(clipBehaviorOf(tester, keyB), Clip.none);
177+
});
178+
});
179+
180+
group('typed routes', () {
181+
test(r'ShellRouteData.$route forwards clipBehavior', () {
182+
final routes = <RouteBase>[GoRoute(path: '/', builder: (_, _) => const Text('Home'))];
183+
184+
expect(
185+
ShellRouteData.$route(factory: (_) => const _ShellRouteData(), routes: routes).clipBehavior,
186+
Clip.hardEdge,
187+
);
188+
expect(
189+
ShellRouteData.$route(
190+
factory: (_) => const _ShellRouteData(),
191+
clipBehavior: Clip.none,
192+
routes: routes,
193+
).clipBehavior,
194+
Clip.none,
195+
);
196+
});
197+
198+
test(r'StatefulShellBranchData.$branch forwards clipBehavior', () {
199+
final routes = <RouteBase>[GoRoute(path: '/', builder: (_, _) => const Text('Home'))];
200+
201+
expect(StatefulShellBranchData.$branch(routes: routes).clipBehavior, Clip.hardEdge);
202+
expect(
203+
StatefulShellBranchData.$branch(routes: routes, clipBehavior: Clip.none).clipBehavior,
204+
Clip.none,
205+
);
206+
});
207+
});
208+
}

0 commit comments

Comments
 (0)