Added useMaterial3 flag to ThemeData. (#93434)

packages/flutter/lib/src/material/theme_data.dart

@@ -231,6 +231,7 @@ class ThemeData with Diagnosticable {
     ScrollbarThemeData? scrollbarTheme,
     InteractiveInkFeatureFactory? splashFactory,
     VisualDensity? visualDensity,
+    bool? useMaterial3,
     // COLOR
     // [colorScheme] is the preferred way to configure colors. The other color
     // properties (as well as brightness, primaryColorBrightness, and primarySwatch)
@@ -387,6 +388,7 @@ class ThemeData with Diagnosticable {
     scrollbarTheme ??= const ScrollbarThemeData();
     splashFactory ??= InkSplash.splashFactory;
     visualDensity ??= VisualDensity.adaptivePlatformDensity;
+    useMaterial3 ??= false;
 
     // COLOR
     assert(colorScheme?.brightness == null || brightness == null || colorScheme!.brightness == brightness);
@@ -518,6 +520,7 @@ class ThemeData with Diagnosticable {
       scrollbarTheme: scrollbarTheme,
       splashFactory: splashFactory,
       visualDensity: visualDensity,
+      useMaterial3: useMaterial3,
       // COLOR
       colorScheme: colorScheme,
       primaryColor: primaryColor,
@@ -619,6 +622,7 @@ class ThemeData with Diagnosticable {
     required this.scrollbarTheme,
     required this.splashFactory,
     required this.visualDensity,
+    required this.useMaterial3,
     // COLOR
     // [colorScheme] is the preferred way to configure colors. The other color
     // properties will gradually be phased out, see
@@ -759,6 +763,7 @@ class ThemeData with Diagnosticable {
        assert(scrollbarTheme != null),
        assert(splashFactory != null),
        assert(visualDensity != null),
+       assert(useMaterial3 != null),
         // COLOR
        assert(colorScheme != null),
        assert(primaryColor != null),
@@ -1078,6 +1083,31 @@ class ThemeData with Diagnosticable {
   /// {@endtemplate}
   final VisualDensity visualDensity;
 
+  /// A temporary flag used to opt-in to new Material 3 features.
+  ///
+  /// If true, then components that have been migrated to Material 3 will
+  /// start using new colors, typography and other features of Material 3.
+  /// If false, they will use the Material 2 look and feel.
+  ///
+  /// Currently no components have been migrated to support Material 3.
+  /// As they are updated to include Material 3 support this documentation
+  /// will be modified to indicate exactly what widgets this flag will affect.
+  ///
+  /// During the migration to Material 3, turning this on may yield
+  /// inconsistent look and feel in your app. Some components will be migrated
+  /// before others and typography changes will be coming in stages.
+  ///
+  /// [useMaterial3] defaults to false. After all the migrated components
+  /// have landed on stable, we will change this to be true by default. After
+  /// that change has landed on stable, we will deprecate this flag and remove
+  /// all uses of it. Everything will use the Material 3 look and feel at
+  /// that point.
+  ///
+  /// See also:
+  ///
+  ///   * [Material Design 3](https://m3.material.io/).
+  final bool useMaterial3;
+
   // COLOR
 
   /// A set of twelve colors that can be used to configure the
@@ -1486,6 +1516,7 @@ class ThemeData with Diagnosticable {
     ScrollbarThemeData? scrollbarTheme,
     InteractiveInkFeatureFactory? splashFactory,
     VisualDensity? visualDensity,
+    bool? useMaterial3,
     // COLOR
     // [colorScheme] is the preferred way to configure colors. The other color
     // properties will gradually be phased out, see
@@ -1632,6 +1663,7 @@ class ThemeData with Diagnosticable {
       scrollbarTheme: scrollbarTheme ?? this.scrollbarTheme,
       splashFactory: splashFactory ?? this.splashFactory,
       visualDensity: visualDensity ?? this.visualDensity,
+      useMaterial3: useMaterial3 ?? this.useMaterial3,
       // COLOR
       colorScheme: (colorScheme ?? this.colorScheme).copyWith(brightness: brightness),
       primaryColor: primaryColor ?? this.primaryColor,
@@ -1800,6 +1832,7 @@ class ThemeData with Diagnosticable {
       scrollbarTheme: ScrollbarThemeData.lerp(a.scrollbarTheme, b.scrollbarTheme, t),
       splashFactory: t < 0.5 ? a.splashFactory : b.splashFactory,
       visualDensity: VisualDensity.lerp(a.visualDensity, b.visualDensity, t),
+      useMaterial3: t < 0.5 ? a.useMaterial3 : b.useMaterial3,
       // COLOR
       colorScheme: ColorScheme.lerp(a.colorScheme, b.colorScheme, t),
       primaryColor: Color.lerp(a.primaryColor, b.primaryColor, t)!,
@@ -1898,6 +1931,7 @@ class ThemeData with Diagnosticable {
         other.scrollbarTheme == scrollbarTheme &&
         other.splashFactory == splashFactory &&
         other.visualDensity == visualDensity &&
+        other.useMaterial3 == useMaterial3 &&
         // COLOR
         other.colorScheme == colorScheme &&
         other.primaryColor == primaryColor &&
@@ -1993,6 +2027,7 @@ class ThemeData with Diagnosticable {
       scrollbarTheme,
       splashFactory,
       visualDensity,
+      useMaterial3,
       // COLOR
       colorScheme,
       primaryColor,
@@ -2088,6 +2123,7 @@ class ThemeData with Diagnosticable {
     properties.add(DiagnosticsProperty<ScrollbarThemeData>('scrollbarTheme', scrollbarTheme, defaultValue: defaultData.scrollbarTheme, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<InteractiveInkFeatureFactory>('splashFactory', splashFactory, defaultValue: defaultData.splashFactory, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<VisualDensity>('visualDensity', visualDensity, defaultValue: defaultData.visualDensity, level: DiagnosticLevel.debug));
+    properties.add(DiagnosticsProperty<bool>('useMaterial3', useMaterial3, defaultValue: defaultData.useMaterial3, level: DiagnosticLevel.debug));
     // COLORS
     properties.add(DiagnosticsProperty<ColorScheme>('colorScheme', colorScheme, defaultValue: defaultData.colorScheme, level: DiagnosticLevel.debug));
     properties.add(ColorProperty('primaryColor', primaryColor, defaultValue: defaultData.primaryColor, level: DiagnosticLevel.debug));

packages/flutter/test/material/theme_data_test.dart

@@ -298,6 +298,7 @@ void main() {
       highlightColor: Colors.black,
       splashColor: Colors.black,
       splashFactory: InkRipple.splashFactory,
+      useMaterial3: false,
       selectedRowColor: Colors.black,
       unselectedWidgetColor: Colors.black,
       disabledColor: Colors.black,
@@ -396,6 +397,7 @@ void main() {
       highlightColor: Colors.white,
       splashColor: Colors.white,
       splashFactory: InkRipple.splashFactory,
+      useMaterial3: true,
       selectedRowColor: Colors.white,
       unselectedWidgetColor: Colors.white,
       disabledColor: Colors.white,
@@ -478,6 +480,7 @@ void main() {
       highlightColor: otherTheme.highlightColor,
       splashColor: otherTheme.splashColor,
       splashFactory: otherTheme.splashFactory,
+      useMaterial3: otherTheme.useMaterial3,
       selectedRowColor: otherTheme.selectedRowColor,
       unselectedWidgetColor: otherTheme.unselectedWidgetColor,
       disabledColor: otherTheme.disabledColor,
@@ -556,6 +559,7 @@ void main() {
     expect(themeDataCopy.highlightColor, equals(otherTheme.highlightColor));
     expect(themeDataCopy.splashColor, equals(otherTheme.splashColor));
     expect(themeDataCopy.splashFactory, equals(otherTheme.splashFactory));
+    expect(themeDataCopy.useMaterial3, equals(otherTheme.useMaterial3));
     expect(themeDataCopy.selectedRowColor, equals(otherTheme.selectedRowColor));
     expect(themeDataCopy.unselectedWidgetColor, equals(otherTheme.unselectedWidgetColor));
     expect(themeDataCopy.disabledColor, equals(otherTheme.disabledColor));
@@ -667,6 +671,7 @@ void main() {
       'scrollbarTheme',
       'splashFactory',
       'visualDensity',
+      'useMaterial3',
       // COLOR
       'colorScheme',
       'primaryColor',