Skip to content

Commit 5351d8c

Browse files
authored
[material_ui, cupertino_ui] Add migration bridge utilities (flutter#12314)
This adds utilities to the material_ui and cupertino_ui to help cover the gap during the ecosystem migration. Users who have migrated their applications can use these utilities to retain compatibility with packages that have not migrated yet. These are marked deprecated as they will be removed in a future major release. Example: ```dart import 'package:material_ui/material_ui.dart'; void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { const MyApp({super.key}); @OverRide Widget build(BuildContext context) { return MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF6750A4)), ), builder: (BuildContext context, Widget? child) { return MaterialUiCompatibilityBridge(child: child!); }, home: const HomeScreen(), ); } } ``` ## 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.
1 parent 44a984d commit 5351d8c

8 files changed

Lines changed: 770 additions & 0 deletions

File tree

‎packages/cupertino_ui/lib/cupertino_ui.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ export 'src/list_tile.dart';
5555
export 'src/localizations.dart';
5656
export 'src/magnifier.dart';
5757
export 'src/menu_anchor.dart';
58+
export 'src/migration_utility.dart';
5859
export 'src/nav_bar.dart';
5960
export 'src/page_scaffold.dart';
6061
export 'src/picker.dart';
Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
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:cupertino_ui/cupertino_ui.dart' as modern; // ignore: prefer_relative_imports
6+
import 'package:flutter/cupertino.dart' as legacy;
7+
import 'package:flutter/widgets.dart';
8+
import 'package:flutter_localizations/flutter_localizations.dart';
9+
10+
/// A bridge widget for applications that have migrated to `package:cupertino_ui`
11+
/// but still contain subtrees or package dependencies using `package:flutter/cupertino.dart`.
12+
///
13+
/// This widget maps the parent [modern.CupertinoThemeData] from `package:cupertino_ui` into
14+
/// a legacy [legacy.CupertinoThemeData] and overrides [legacy.Localizations] with delegates
15+
/// so that legacy widgets in [child] can resolve `legacy.CupertinoTheme.of(context)` and
16+
/// `legacy.CupertinoLocalizations.of(context)`.
17+
///
18+
/// ## App-wide usage
19+
///
20+
/// The recommended way to use this bridge across an entire application is to
21+
/// wrap the app once using [modern.CupertinoApp.builder]:
22+
///
23+
/// ```dart
24+
/// import 'package:cupertino_ui/cupertino_ui.dart';
25+
///
26+
/// void main() {
27+
/// runApp(const MyApp());
28+
/// }
29+
///
30+
/// class MyApp extends StatelessWidget {
31+
/// const MyApp({super.key});
32+
///
33+
/// @override
34+
/// Widget build(BuildContext context) {
35+
/// return CupertinoApp(
36+
/// theme: const CupertinoThemeData(
37+
/// primaryColor: CupertinoColors.systemIndigo,
38+
/// ),
39+
/// builder: (BuildContext context, Widget? child) {
40+
/// return CupertinoUiCompatibilityBridge(child: child!);
41+
/// },
42+
/// home: const HomeScreen(),
43+
/// );
44+
/// }
45+
/// }
46+
/// ```
47+
///
48+
/// ## Subtree usage
49+
///
50+
/// Alternatively, wrap specific legacy package widgets or subtrees:
51+
///
52+
/// ```dart
53+
/// import 'package:cupertino_ui/cupertino_ui.dart';
54+
/// import 'package:some_legacy_package/some_legacy_package.dart';
55+
///
56+
/// class MyScreen extends StatelessWidget {
57+
/// const MyScreen({super.key});
58+
///
59+
/// @override
60+
/// Widget build(BuildContext context) {
61+
/// return CupertinoPageScaffold(
62+
/// navigationBar: const CupertinoNavigationBar(
63+
/// middle: Text('Migrated Screen'),
64+
/// ),
65+
/// child: CupertinoUiCompatibilityBridge(
66+
/// child: LegacyPackageWidget(),
67+
/// ),
68+
/// );
69+
/// }
70+
/// }
71+
/// ```
72+
@Deprecated(
73+
'CupertinoUiCompatibilityBridge is a temporary migration utility intended for use only while '
74+
'dependencies are being migrated to package:cupertino_ui. '
75+
'This feature was deprecated to indicate it will be removed in a future release.',
76+
)
77+
class CupertinoUiCompatibilityBridge extends StatelessWidget {
78+
/// Creates a [CupertinoUiCompatibilityBridge].
79+
@Deprecated(
80+
'CupertinoUiCompatibilityBridge is a temporary migration utility intended for use only while '
81+
'dependencies are being migrated to package:cupertino_ui. '
82+
'This feature was deprecated to indicate it will be removed in a future release.',
83+
)
84+
const CupertinoUiCompatibilityBridge({super.key, required this.child, this.delegates});
85+
86+
/// The widget below this widget in the tree.
87+
final Widget child;
88+
89+
/// The localizations delegates for legacy widgets.
90+
///
91+
/// Defaults to `[GlobalCupertinoLocalizations.delegate, GlobalWidgetsLocalizations.delegate]`.
92+
final List<LocalizationsDelegate<dynamic>>? delegates;
93+
94+
@override
95+
Widget build(BuildContext context) {
96+
final modern.CupertinoThemeData modernTheme = modern.CupertinoTheme.of(context);
97+
98+
return legacy.CupertinoTheme(
99+
data: _mapToLegacy(modernTheme),
100+
child: legacy.Localizations.override(
101+
context: context,
102+
delegates:
103+
delegates ??
104+
const <LocalizationsDelegate<dynamic>>[
105+
GlobalCupertinoLocalizations.delegate,
106+
GlobalWidgetsLocalizations.delegate,
107+
],
108+
child: child,
109+
),
110+
);
111+
}
112+
113+
legacy.CupertinoThemeData _mapToLegacy(modern.CupertinoThemeData modernTheme) {
114+
return legacy.CupertinoThemeData(
115+
brightness: modernTheme.brightness,
116+
primaryColor: modernTheme.primaryColor,
117+
primaryContrastingColor: modernTheme.primaryContrastingColor,
118+
barBackgroundColor: modernTheme.barBackgroundColor,
119+
scaffoldBackgroundColor: modernTheme.scaffoldBackgroundColor,
120+
selectionHandleColor: modernTheme.selectionHandleColor,
121+
applyThemeToAll: modernTheme.applyThemeToAll,
122+
textTheme: legacy.CupertinoTextThemeData(
123+
primaryColor: modernTheme.primaryColor,
124+
textStyle: modernTheme.textTheme.textStyle,
125+
actionTextStyle: modernTheme.textTheme.actionTextStyle,
126+
actionSmallTextStyle: modernTheme.textTheme.actionSmallTextStyle,
127+
tabLabelTextStyle: modernTheme.textTheme.tabLabelTextStyle,
128+
navTitleTextStyle: modernTheme.textTheme.navTitleTextStyle,
129+
navLargeTitleTextStyle: modernTheme.textTheme.navLargeTitleTextStyle,
130+
navActionTextStyle: modernTheme.textTheme.navActionTextStyle,
131+
pickerTextStyle: modernTheme.textTheme.pickerTextStyle,
132+
dateTimePickerTextStyle: modernTheme.textTheme.dateTimePickerTextStyle,
133+
),
134+
);
135+
}
136+
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds CupertinoUiCompatibilityBridge for legacy flutter/cupertino.dart compatibility.
3+
version: minor
Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
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+
// ignore_for_file: deprecated_member_use
6+
7+
import 'package:cupertino_ui/cupertino_ui.dart' as modern;
8+
import 'package:flutter/cupertino.dart' as legacy;
9+
import 'package:flutter/widgets.dart';
10+
import 'package:flutter_localizations/flutter_localizations.dart';
11+
import 'package:flutter_test/flutter_test.dart';
12+
13+
void main() {
14+
testWidgets('CupertinoUiCompatibilityBridge provides mapped CupertinoThemeData properties', (
15+
WidgetTester tester,
16+
) async {
17+
legacy.CupertinoThemeData? capturedLegacyTheme;
18+
19+
const modernThemeData = modern.CupertinoThemeData(
20+
brightness: Brightness.dark,
21+
primaryColor: Color(0xFF00FF00),
22+
primaryContrastingColor: Color(0xFFFF0000),
23+
barBackgroundColor: Color(0xFF111111),
24+
scaffoldBackgroundColor: Color(0xFF222222),
25+
);
26+
27+
await tester.pumpWidget(
28+
modern.CupertinoApp(
29+
theme: modernThemeData,
30+
home: modern.CupertinoUiCompatibilityBridge(
31+
child: Builder(
32+
builder: (BuildContext context) {
33+
capturedLegacyTheme = legacy.CupertinoTheme.of(context);
34+
return const SizedBox.shrink();
35+
},
36+
),
37+
),
38+
),
39+
);
40+
41+
expect(capturedLegacyTheme, isNotNull);
42+
expect(capturedLegacyTheme!.brightness, modernThemeData.brightness);
43+
expect(capturedLegacyTheme!.primaryColor, modernThemeData.primaryColor);
44+
expect(capturedLegacyTheme!.primaryContrastingColor, modernThemeData.primaryContrastingColor);
45+
expect(capturedLegacyTheme!.barBackgroundColor, modernThemeData.barBackgroundColor);
46+
expect(capturedLegacyTheme!.scaffoldBackgroundColor, modernThemeData.scaffoldBackgroundColor);
47+
});
48+
49+
testWidgets('CupertinoUiCompatibilityBridge maps CupertinoTextThemeData properties', (
50+
WidgetTester tester,
51+
) async {
52+
legacy.CupertinoThemeData? capturedLegacyTheme;
53+
54+
const modernTextTheme = modern.CupertinoTextThemeData(
55+
navTitleTextStyle: TextStyle(fontSize: 20.0, fontWeight: FontWeight.bold),
56+
actionTextStyle: TextStyle(fontSize: 16.0, color: Color(0xFF123456)),
57+
);
58+
59+
const modernThemeData = modern.CupertinoThemeData(textTheme: modernTextTheme);
60+
61+
await tester.pumpWidget(
62+
modern.CupertinoApp(
63+
theme: modernThemeData,
64+
home: modern.CupertinoUiCompatibilityBridge(
65+
child: Builder(
66+
builder: (BuildContext context) {
67+
capturedLegacyTheme = legacy.CupertinoTheme.of(context);
68+
return const SizedBox.shrink();
69+
},
70+
),
71+
),
72+
),
73+
);
74+
75+
expect(capturedLegacyTheme, isNotNull);
76+
expect(
77+
capturedLegacyTheme!.textTheme.navTitleTextStyle.fontSize,
78+
modernTextTheme.navTitleTextStyle.fontSize,
79+
);
80+
expect(
81+
capturedLegacyTheme!.textTheme.navTitleTextStyle.fontWeight,
82+
modernTextTheme.navTitleTextStyle.fontWeight,
83+
);
84+
expect(
85+
capturedLegacyTheme!.textTheme.actionTextStyle.color,
86+
modernTextTheme.actionTextStyle.color,
87+
);
88+
});
89+
90+
testWidgets('CupertinoUiCompatibilityBridge provides CupertinoLocalizations', (
91+
WidgetTester tester,
92+
) async {
93+
legacy.CupertinoLocalizations? capturedLegacyLocalizations;
94+
95+
await tester.pumpWidget(
96+
modern.CupertinoApp(
97+
home: modern.CupertinoUiCompatibilityBridge(
98+
child: Builder(
99+
builder: (BuildContext context) {
100+
capturedLegacyLocalizations = legacy.CupertinoLocalizations.of(context);
101+
return const SizedBox.shrink();
102+
},
103+
),
104+
),
105+
),
106+
);
107+
108+
expect(capturedLegacyLocalizations, isNotNull);
109+
expect(capturedLegacyLocalizations!.datePickerDateOrder, isNotNull);
110+
expect(capturedLegacyLocalizations!.modalBarrierDismissLabel, isNotEmpty);
111+
});
112+
113+
testWidgets('CupertinoUiCompatibilityBridge allows rendering legacy Cupertino widgets', (
114+
WidgetTester tester,
115+
) async {
116+
await tester.pumpWidget(
117+
modern.CupertinoApp(
118+
home: modern.CupertinoUiCompatibilityBridge(
119+
child: legacy.CupertinoPageScaffold(
120+
navigationBar: const legacy.CupertinoNavigationBar(middle: Text('Legacy Title')),
121+
child: Center(
122+
child: legacy.CupertinoButton(onPressed: () {}, child: const Text('Legacy Button')),
123+
),
124+
),
125+
),
126+
),
127+
);
128+
129+
expect(find.text('Legacy Title'), findsOneWidget);
130+
expect(find.text('Legacy Button'), findsOneWidget);
131+
expect(find.byType(legacy.CupertinoButton), findsOneWidget);
132+
expect(find.byType(legacy.CupertinoPageScaffold), findsOneWidget);
133+
});
134+
135+
testWidgets('CupertinoUiCompatibilityBridge supports custom delegates', (
136+
WidgetTester tester,
137+
) async {
138+
legacy.CupertinoLocalizations? capturedLegacyLocalizations;
139+
140+
await tester.pumpWidget(
141+
modern.CupertinoApp(
142+
home: modern.CupertinoUiCompatibilityBridge(
143+
delegates: const <LocalizationsDelegate<dynamic>>[GlobalCupertinoLocalizations.delegate],
144+
child: Builder(
145+
builder: (BuildContext context) {
146+
capturedLegacyLocalizations = legacy.CupertinoLocalizations.of(context);
147+
return const SizedBox.shrink();
148+
},
149+
),
150+
),
151+
),
152+
);
153+
154+
expect(capturedLegacyLocalizations, isNotNull);
155+
expect(capturedLegacyLocalizations!.modalBarrierDismissLabel, isNotEmpty);
156+
});
157+
158+
testWidgets('CupertinoUiCompatibilityBridge works at root in CupertinoApp.builder', (
159+
WidgetTester tester,
160+
) async {
161+
await tester.pumpWidget(
162+
modern.CupertinoApp(
163+
builder: (BuildContext context, Widget? child) {
164+
return modern.CupertinoUiCompatibilityBridge(child: child!);
165+
},
166+
home: modern.CupertinoPageScaffold(
167+
child: Column(
168+
children: <Widget>[
169+
modern.CupertinoButton(onPressed: () {}, child: const Text('Modern Button')),
170+
legacy.CupertinoButton(onPressed: () {}, child: const Text('Legacy Button')),
171+
],
172+
),
173+
),
174+
),
175+
);
176+
177+
expect(find.text('Modern Button'), findsOneWidget);
178+
expect(find.text('Legacy Button'), findsOneWidget);
179+
expect(find.byType(modern.CupertinoButton), findsOneWidget);
180+
expect(find.byType(legacy.CupertinoButton), findsOneWidget);
181+
});
182+
}

‎packages/material_ui/lib/material_ui.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ export 'src/menu_button_theme.dart';
129129
export 'src/menu_style.dart';
130130
export 'src/menu_theme.dart';
131131
export 'src/mergeable_material.dart';
132+
export 'src/migration_utility.dart';
132133
export 'src/motion.dart';
133134
export 'src/navigation_bar.dart';
134135
export 'src/navigation_bar_theme.dart';

0 commit comments

Comments
 (0)