More version 5.1.0 features and fixes

CHANGELOG.md

@@ -1,6 +1,176 @@
 # Changelog
 
-All notable changes to the **FlexColorScheme** package are documented here.
+All notable changes to the **FlexColorScheme** (FCS) package are documented here.
+
+## v5.1.0 - July 8, 2022
+
+* Updated to support Flutter 3.0.0, Dart 2.17 and latest Flutter package dependencies in
+  example apps. Requires at least Flutter 3.0.0 and Dart 2.17.0.
+
+**NEW**
+
+* **Added** full support for in Flutter 3.0.0 new `ColorScheme.surfaceTint` color. It is set to 
+  `ColorScheme.primary` color by default, as Flutter and Material 3 does. If a custom `surfaceTint` 
+  color is provided, it is also used as the blend color, instead of `primary` color, for 
+  FlexColorScheme's surface blend feature.
+
+* **Added** pass through API for using Flutter 3.0.0 theme extensions directly via FlexColorScheme 
+  API. It was added as a convenience feature in order to avoid having to add theme extensions with a
+ `copyWith` on FlexColorScheme produced ThemeData. With the `FlexColorScheme.extensions` and
+ `FlexThemeData.extensions` properties you can add custom theme extensions directly.
+
+**DEPRECATED**
+
+* **Deprecated:** `FlexColorScheme.m3TextTheme`. The custom M3 text theme is no longer needed after 
+  Flutter 3.0.0 release that includes the new M3 Typography in addition to its earlier released
+  `TextTheme`. You can opt in on using the new M3 style TextTheme as before by setting 
+  `FlexColorScheme.subThemesData.useTextTheme` to true **or** by setting 
+  `FlexColorScheme.useMaterial3` to true. Using either does however come with known issue
+  [#103864](https://github.com/flutter/flutter/issues/103864), where dynamically switching 
+  Typography, e.g. from 2014 or 2018, to M3 2021 Typography, triggers the mentioned assert in issue
+  [#103864](https://github.com/flutter/flutter/issues/103864). This issue has always existed in
+  Flutter SDK ThemeData when dynamically changing between different Typography. 
+  Before FlexColorScheme avoided triggering this issue by only using Typography 2018, also when 
+  opting in on M3 TextTheme, that before used 2018 based Typography to make a custom M3 like 
+  `TextTheme`. Avoiding this issue is no longer possible when opting in on M3, that now correctly 
+  uses its own and different Typography from M2. This exposes this issue if you dynamically 
+  change ThemeData from one to another Typography.
+  To avoid this Flutter SDK issue, use the same Typography for all your themes in your app and don't
+  dynamically switch theme between ThemeData objects that uses different Typography in your 
+  application. The use cases for doing this are few, but it is still a Flutter SDK limitation to be
+  aware about.
+
+* **Deprecated:** `FlexSubThemes.buttonTheme` that creates an opinionated `ButtonThemeData`.
+  The ButtonThemeData is marked as obsolete in Flutter SDK, but not yet deprecated in 
+  Flutter version 3.0.0. FlexColorscheme now marks it as **deprecated**. It will be 
+  removed in a future FlexColorScheme release when Flutter SDK deprecates `ButtonThemeData`.
+
+**M3 STYLE FIXES AND CHANGES**
+
+* **FAB M3 defaults change**: Floating Action Button background color, will when opting in on 
+  `ThemeData.useMaterail3`, use color `theme.colorScheme.primaryContainer`, 
+  otherwise `theme.colorScheme.secondary` is used.
+
+* **Input Decorator default change**: The `TextField` and its `InputDecorator` border radius 
+  default value was changed from 20dp to 16dp when using opinionated component themes.
+  If opting in on Material 3, the default value for M3 design is used, which is only 4dp.
+  See specification https://m3.material.io/components/text-fields/specs.
+  Flutter 3.0.x does not yet implement the new M3 TextField style, but via this change when
+  opting in on M3, FlexColorScheme offers an early approximation of it. 
+
+* **NavigationBar M3 defaults change**: Default colors of `NavigationBar` when opting in on 
+  `useMaterial3` and not using opinionated component themes will now match M3 default colors. 
+  The background color will follow M3 style also by default when component themes are enabled and
+  `useMaterial3` is true. This style is difficult to replicate with a single color otherwise.  
+  The difference is subtle for FCS surface tinted background colors. You can still set it to
+  `background` color to replicate past FCS default color when sub-themes were enabled. 
+  For other properties, if opinionated component themes are not used, FCS will use default M3
+  theme styles on `NavigationBar` when `useMaterial3` is true. If opting in
+  on opinionated component themes, FCS uses its own custom opinionated default style. Which can be
+  modified to be the same as default M3 style too, just as before. The change also includes a 
+  default font size change for FCS opinionated styled navigation bar, from 11dp to 12dp. This change
+  was done to harmonize it with its M3 style.
+
+* **NavigationRail M3 defaults change**: Default colors of `NavigationRail` when opting in on
+  `useMaterial3` and not using opinionated component themes will now match M3 default colors. 
+  If opinionated component themes are not used, FCS will use default M3 theme styles on 
+  `NavigationRail` when `useMaterial3` is true. If opting in on opinionated component themes, 
+  FCS uses its own custom opinionated default style. Which can be modified to be the same as 
+  default M3 style too, just as before. The change also includes a default font
+  size change for FCS opinionated styled rail, from 14dp to 12dp.  This change was
+  done to harmonize it with its M3 style.
+
+* **Toggleable M3 style change:** Default color of toggles (Switch, CheckBox and Radio) are now 
+  using `primary` color as default themed color when opting in on opinionated component themes or
+  setting `ThemeData.useMaterail3` to true. The Switch, CheckBox and Radio themes then use a style
+  that match the M3 color design intent. In it, 
+  switches and toggles are mostly primary color based. In M3 color design, the secondary color is a 
+  poor choice for switches and toggles, and it is therefore not used as their default color. It 
+  does not look nice with M3 based ColorSchemes, created e.g. using M3 color seeding. If you use a
+  custom M3 color design, where secondary color is still prominent, you can of course still use it.
+
+* **Fixed lint:** "Avoid using private types in public APIs". See tweet 
+  [discussion](https://twitter.com/RydMike/status/1533788260320923649) about why and when you 
+  might run into this lint being triggered by older Stateful Widgets. The lint warning was
+  addressed in the package and examples.
+
+**EXAMPLE UPDATES**
+
+* Added a **Theme Extensions** example to the default example app, i.e. the "Hot Reload Playground".
+
+* Themes Playground: Updated the default style info labels for Switch, CheckBox and Radio.
+
+* Themes Playground: To the top row theme selector, where the FlexColorScheme and component themes  
+  switches are, added the "Use Material 3" toggle. Previously this toggle was only available on the
+  introduction panel. The availability in the header makes it easy to toggle it ON and OFF at
+  any time, to see what impact it has on widgets.
+
+* Themes Playground: Updated the default style info labels for the NavigationBar. The logic to display 
+  default color labels in different config modes (M2/M3/FCS/FCS+M2/FCS+M3) is quite involved, please 
+  report any issues. 
+
+* Themes Playground: Updated the default style info labels for the NavigationRail. The logic to display
+  default color labels in different config modes (M2/M3/FCS/FCS+M2/FCS+M3) is quite involved, please
+  report any issues.
+
+* Themes Playground: Due to issue [#107190](https://github.com/flutter/flutter/issues/107190), the
+  Playground previous default to use Material 3 was changed to false. 
+
+* Added support in Themes Playground to customize the `surfaceTint` color. It controls both the
+  elevation color used for elevated `Material` surfaces in M3. Plus for FlexColorScheme it is also 
+  used as the surface blend color. By default, the `surfaceTint` color equals `ColorScheme.primary` 
+  color. Generally there are not many good design reasons to change the color, but it is now 
+  possible to do so. A good graphical designer can use it to create subtle difference from the 
+  standard surface elevation color branding effects. Used poorly, it mostly creates not so  
+  appealing visual and coloring results.
+
+**KNOWN FLUTTER SDK ISSUES**
+
+The issues below in the Flutter SDK itself, are known to impact FlexColorScheme and Flutter 
+theming in general.
+
+* Switching Typography dynamically in Flutter SDK ThemeData is broken, see
+  issue [#103864](https://github.com/flutter/flutter/issues/103864) for more information.
+  If it is done and the error ignored, an app doing so eventually become unstable.
+
+* The Themes Playground app contains a workaround to
+  avoid issue [#103864](https://github.com/flutter/flutter/issues/103864). The workaround
+  is done by always using 2021 Typography, but simulating 2018 Typography. This is done by using
+  a custom TextTheme that looks like 2018 Typography is used when using M2 theme mode. The
+  Playground App actually always stays in 2021 Typography, but looks 
+  like it switches it. Which it does by applying a custom `TextTheme` in 2021 Typography, that looks
+  like 2018 Typography is used. All other examples also avoid the issue by only using the 
+  M3 2021 Typography and not even mimicking a switch between M2 and M3 Typography. 
+
+  The above workaround is needed because the Playground app has toggles that switches Typography
+  frequently, without the workaround it will eventually crash. With this workaround it never
+  switches Typography, it just looks like it does, but app stays in 2021 Typography all the time.
+  The by Themes Playground generated ThemeData config will use the actual real effective 
+  Typography. This is also fine, since an app using the theme will likely never switch used 
+  Typography. However, if it does, it will face the same issue the Playground app did. The issue
+  is a Flutter SDK issue that FlexColorScheme cannot fix. Most likely 99% of apps will never run 
+  into this issue.
+
+* In Flutter SDK 3.0.x, when opting in on `useMaterial3:true`, the `Material` widget and other SDK 
+  widgets built on it, gets no elevation when only the `elevation` property is defined. It is 
+  required to also define `shadowColor` and/or `surfaceTintColor` to get any elevation effect.
+  When using the `Material` widget itself this is easy to address. However, widgets like
+  `Drawer`, `PopupMenuButton`, `BottomNavigationBar`, `NavigationRail`, `Dialog`, `AlertDialog`,
+  `TimePickerDialog`, `DatePickerDialog`, `MaterialBanner` and `BottomSheet` do not expose these 
+  `Material` properties and cannot be elevated. 
+
+  The issue is reported and tracked here [#107190](https://github.com/flutter/flutter/issues/107190) 
+  and also mentioned in the `FlexColorScheme` repo here
+  [#54](https://github.com/rydmike/flex_color_scheme/issues/54). There are no good workarounds 
+  for using elevation on these widgets when `useMaterial3` is true. The options are to not use
+  M3, if such elevations are important to your app design. One working fix is to wrap those widgets
+  in a theme where `useMaterial3` is false, then te rest of your app can still use it. This is 
+  however a rather tedious workaround fix. Due to current SDK `Material` elevation issues when 
+  `useMaterial3` is true, it is recommended to not use it yet.
+
+* This regression in master channel impacts AppBar icon colors when using Material 3 
+  [#107305](https://github.com/flutter/flutter/issues/107305). It has not yet landed in stable 
+  channel Flutter 3.0.4, but if you use master channel it is something to be aware of.
 
 ## v5.1.0 - July 5, 2022
 
@@ -1792,9 +1962,8 @@ tracked [here](https://github.com/rydmike/flex_color_scheme/projects/1).
 
 ## PLANNED
 
-- All past planned features have been done and delivered with version 5,
-  and much more actually. Future planned topics will be listed in
-  the documentation.
+- All past planned features have been done and delivered with version 5.
+  Future planned topics will be listed in the documentation or repo discussions.
 
 ## DONE
 

example/lib/example1/main.dart

@@ -1,4 +1,5 @@
 import 'package:flex_color_scheme/flex_color_scheme.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 
 import '../shared/utils/app_scroll_behavior.dart';
@@ -42,12 +43,22 @@ class _DemoAppState extends State<DemoApp> {
         scheme: usedScheme,
         // Use very subtly themed app bar elevation in light mode.
         appBarElevation: 0.5,
+        // Use predefined M3 typography while this issue is in effect:
+        // https://github.com/flutter/flutter/issues/103864
+        typography: Typography.material2021(
+          platform: defaultTargetPlatform,
+        ),
       ),
       // Same definition for the dark theme, but using FlexThemeData.dark().
       darkTheme: FlexThemeData.dark(
         scheme: usedScheme,
         // Use a bit more themed elevated app bar in dark mode.
         appBarElevation: 2,
+        // Use predefined M3 typography while this issue is in effect:
+        // https://github.com/flutter/flutter/issues/103864
+        typography: Typography.material2021(
+          platform: defaultTargetPlatform,
+        ),
       ),
       // Use the above dark or light theme based on active themeMode.
       themeMode: themeMode,

example/lib/example2/main.dart

@@ -1,4 +1,5 @@
 import 'package:flex_color_scheme/flex_color_scheme.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:google_fonts/google_fonts.dart';
 
@@ -151,6 +152,11 @@ class DemoApp extends StatelessWidget {
               // textTheme and primaryTextTheme in FlexThemeData. This is
               // just how you would use it with ThemeData too.
               fontFamily: GoogleFonts.notoSans().fontFamily,
+              // Use predefined M3 typography while this issue is in effect:
+              // https://github.com/flutter/flutter/issues/103864
+              typography: Typography.material2021(
+                platform: defaultTargetPlatform,
+              ),
             ),
             // Same setup for the dark theme, but using FlexThemeData.dark().
             darkTheme: FlexThemeData.dark(
@@ -161,6 +167,11 @@ class DemoApp extends StatelessWidget {
               appBarElevation: 1,
               visualDensity: VisualDensity.standard,
               fontFamily: GoogleFonts.notoSans().fontFamily,
+              // Use predefined M3 typography while this issue is in effect:
+              // https://github.com/flutter/flutter/issues/103864
+              typography: Typography.material2021(
+                platform: defaultTargetPlatform,
+              ),
             ),
             // Use the dark or light theme, based on theme controller setting.
             themeMode: themeController.themeMode,

example/lib/example3/main.dart

@@ -1,4 +1,5 @@
 import 'package:flex_color_scheme/flex_color_scheme.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:google_fonts/google_fonts.dart';
 
@@ -174,6 +175,11 @@ class DemoApp extends StatelessWidget {
             // not as large as on hand held devices.
             visualDensity: FlexColorScheme.comfortablePlatformDensity,
             fontFamily: GoogleFonts.notoSans().fontFamily,
+            // Use predefined M3 typography while this issue is in effect:
+            // https://github.com/flutter/flutter/issues/103864
+            typography: Typography.material2021(
+              platform: defaultTargetPlatform,
+            ),
           ),
           // We make an equivalent definition for the dark theme, but using
           // FlexThemeData.dark() and the dark FlexSchemeColors instead.
@@ -199,6 +205,11 @@ class DemoApp extends StatelessWidget {
             ),
             visualDensity: FlexColorScheme.comfortablePlatformDensity,
             fontFamily: GoogleFonts.notoSans().fontFamily,
+            // Use predefined M3 typography while this issue is in effect:
+            // https://github.com/flutter/flutter/issues/103864
+            typography: Typography.material2021(
+              platform: defaultTargetPlatform,
+            ),
           ),
           // Use the dark or light theme, based on controller setting.
           themeMode: themeController.themeMode,

example/lib/example4/main.dart

@@ -1,4 +1,5 @@
 import 'package:flex_color_scheme/flex_color_scheme.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 
 import '../shared/const/app_color.dart';
@@ -166,6 +167,11 @@ class DemoApp extends StatelessWidget {
             // from a single static source, so we can change it easily there.
             visualDensity: AppData.visualDensity,
             fontFamily: AppData.font,
+            // Use predefined M3 typography while this issue is in effect:
+            // https://github.com/flutter/flutter/issues/103864
+            typography: Typography.material2021(
+              platform: defaultTargetPlatform,
+            ),
           ),
           // We do the exact same definition for the dark theme, but using
           // FlexThemeData.dark() and the dark FlexSchemeColors in our
@@ -191,6 +197,11 @@ class DemoApp extends StatelessWidget {
                 : null,
             visualDensity: AppData.visualDensity,
             fontFamily: AppData.font,
+            // Use predefined M3 typography while this issue is in effect:
+            // https://github.com/flutter/flutter/issues/103864
+            typography: Typography.material2021(
+              platform: defaultTargetPlatform,
+            ),
           ),
           // Use the dark or light theme based on controller setting.
           themeMode: themeController.themeMode,

example/lib/example5/widgets/panels/component_themes/component_themes.dart

@@ -62,7 +62,7 @@ class ComponentThemes extends StatelessWidget {
         ListTile(
           enabled: controller.useSubThemes && controller.useFlexColorScheme,
           title: const Text('Global border radius on components'),
-          subtitle: const Text('Default setting uses Material 3 design '
+          subtitle: const Text('Default setting uses mostly Material 3 design '
               'values, where radius spec varies per component. '
               'Material 2 design uses 4 on all components. '
               'If you set a value, all components will use it. '

example/lib/example5/widgets/panels/text_field_settings/text_field_settings.dart

@@ -16,7 +16,9 @@ class TextFieldSettings extends StatelessWidget {
     final String decoratorRadiusDefaultLabel =
         controller.inputDecoratorBorderRadius == null &&
                 controller.defaultRadius == null
-            ? 'default 20'
+            ? controller.useMaterial3
+                ? 'default 4'
+                : 'default 16'
             : controller.inputDecoratorBorderRadius == null &&
                     controller.defaultRadius != null
                 ? 'global ${controller.defaultRadius!.toStringAsFixed(0)}'

example/lib/example5/widgets/shared/color_picker_inkwell.dart

@@ -225,13 +225,6 @@ class ColorPickerInkWell extends StatelessWidget {
     final bool isLight = Theme.of(context).brightness == Brightness.light;
 
     return InkWell(
-      // TODO(rydmike): Remove this commented customized InkWell style.
-      // We want a bit more pronounced hover color for this case than normally.
-      // hoverColor: isLight ? const Color(0x40BCBCBC):const Color(0x30FFFFFF),
-      // splashColor: isLight ? const Color(0x40BCBCBC):const Color(0x30FFFFFF),
-      // focusColor: isLight ? const Color(0x40BCBCBC):const Color(0x30FFFFFF),
-      // highlightColor:
-      //     isLight ? const Color(0x40BCBCBC) : const Color(0x30FFFFFF),
       onHover: (bool value) {
         onHover?.call(value);
       },