Migrate deprecated CorePalette / Scheme APIs to CorePalettes + DynamicScheme

[guidezpl]

Package

dynamic_color

Description

Migrate from depprecated APIs

• CorePalette.fromList
• Scheme.lightFromCorePalette
• Scheme.darkFromCorePalette

to

• CorePalettes
• DynamicScheme (and concrete implementations like SchemeTonalSpot

Contrast

In doing so, we'll also be able to leverage Material's / Android's multi-level contrast:

Expected vs actual result:

1. Material 3 has introduced user-controlled color contrast which allows users to select three levels of contrast:
   
2. According to the linked specification, the color scheme should "automatically" inherit the system contrast settings. However, the dynamic_color plugin does not respect this setting. The colors provided by the plugin are always the same irrespective of the contrast setting.

Steps to reproduce:

1. Create a Flutter app and add the dynamic_color package.
2. Use DynamicColorBuilder to get the light and dark color schemes.
3. Run the app on Android where the contrast setting is supported. To change the contrast, go to Developer Options > Contrast.
4. After changing the contrast, open another app where dynamic color is supported like Google Drive to observe the differences.
5. Reopen the Flutter app. It can be observed that the colors do not change as per the selected contrast option.

[guidezpl]

WIP https://docs.google.com/document/d/1jaJskF2S3OFEKygtncqfTqZu91-onviiSENFSfUQjY8/edit

[12people]

@guidezpl

Was this a way to expose the Variant enum from material_color_utilities? What's the status now?

[helomri]

I have done some research and I have established a plan about how to migrate from those old APIs to ColorPalettes / DynamicScheme.

---

Currently, depending on the platform, we receive either the equivalent of a ColorPalettes object (only on Android) or an accent color (on other platforms). We’ll need to create DynamicSchemes objects for those two cases. A DynamicScheme is comprised of :

• A source color (sourceColorHct) : it is the equivalent of the accent color we receive from other platforms than Android ;
• A color variant (variant) : themes used to control the style of colorways from the palettes ;
• A contrast level (contrastLevel) : the level of contrast to apply to the DynamicColors we use to generate ColorSchemes later ;
• A brightness (isDark).
• 6 TonalPalettes (primaryPalette, secondaryPalette, tertiaryPalette, neutralPalette, neutralVariantPalette, errorPalette) : it is the equivalent of a CorePalettes object plus a palette for errors ;

From what I understand about those legacy APIs, the scheme we currently receive from platforms other than Android is using the tonal spot variant (actually, it is an undefined variant that does not have any equivalent) and a contrast level of 0 (standard), the tonal palettes are derived automatically from the variant.

On Android, the OS provides the different palettes but does not give any information about the variant or source color that is being used (since OEMs may wish to use custom colorways or completely different color systems). This means we have no way to reliably assign a variant on DynamicScheme. We could either make DynamicScheme.variant nullable upstream or simply always set the variant parameter to Variant.tonalSpot by default on Android. The actual value is purely informative, so as long as we keep the DynamicScheme private and keep this in mind, no issues should arise. (The variant value does matter in tonal palette generation as well as in actual dynamic color generation, I do not see any way to bypass this except transferring all theme colors and declaring themes for different brightness and contrast in Android, which seems out of scope...)

On other platforms, we can simply derive the different tonal palettes from the tonal spot variant or expose a parameter to use a specific variant, but make it clear that it won’t work exactly on Android.

---

In the MaterialApp constructor, there are currently 4 ThemeData parameters of which we can only provide color schemes for two :

• theme (light, normal contrast)
• darkTheme (dark, normal contrast)
• highContrastTheme (light, high contrast)
• highContrastDarkTheme (dark, high contrast)

Support for medium contrast color schemes is currently lacking in Flutter, but will almost certainly be added in the future.

This means we would necessarily have to update the signature for the callback inside DynamicColorBuilder in one of two ways :

1. We could keep the same structure and add more parameters :

/// Builds the child widget of this widget, providing light and dark  
/// [ColorScheme]s for different contrast levels.  
///  
/// The [ColorScheme]s will be null if dynamic color is not supported on the  
/// platform, or if the OS has yet to respond.  
final Widget Function(  
  ColorScheme? lightDynamic,  
  ColorScheme? lightMediumContrastDynamic,  
  ColorScheme? lightHighContrastDynamic,  
  ColorScheme? darkMediumContrastDynamic,  
  ColorScheme? darkHighContrastDynamic,  
) contrastBuilder;  

2. Alternatively, we could create an object that would enable the developer to lazily create the color schemes they need like this :

abstract class DynamicColorSchemeFactory {  
  const DynamicColorSchemeFactory();

  ColorScheme? generate({required Brightness brightness, double contrast = 0.0});

  ColorScheme? get light => generate(brightness: Brightness.light);  
  ColorScheme? get dark => generate(brightness: Brightness.dark);

  ColorScheme? get lightMediumContrast => generate(brightness: Brightness.light, contrast: .5);  
  ColorScheme? get darkMediumContrast => generate(brightness: Brightness.dark, contrast: .5);

  ColorScheme? get lightHighContrast => generate(brightness: Brightness.light, contrast: 1);  
  ColorScheme? get darkHighContrast => generate(brightness: Brightness.dark, contrast: 1);  
}  

We would have one implementation for Android and another for other platforms. This system would lower the risk of having other breaking changes later as the new builder would only have one argument.

To support developers during the transition, we should deprecate the legacy builder and make both builders nullable, and assert either one is defined in the constructor. This will let time for developers to update their apps. Later, we will make the new builder required and non-nullable, and delete builder.

---

As for DynamicColorPlugin, getAccentColor will stay as-is but getCorePalette will need to be deprecated (as it inherently returns a CorePalette). We will add a third method named getTonalPalettes which will include the same color values as an int list and the error palette. We will expose a new static method with the same name that will return a List<TonalPalette>.

I do not see any issues why we can't simply create a new extension method to turn a DynamicScheme into a ColorScheme and use that as a replacement for CorePalette.toColorScheme (which we will also deprecate).

---

I think it is simpler to directly set the variant for the DynamicScheme to tonal spot (by default), as clearly the object's use is very localized and the variant is not checked often (or at all in this case). And I believe the DynamicColorSchemeFactory is the way to go since it should make the public APIs more robust and less prone to breaking changes.

I haven't yet looked much into testing, but it seems like adding mock CorePalettes would work in the same way we currently use accent colors for testing (we would have to use the TonalScheme construcor i.e, extract the colors from it, and insert them in the mock method call handler for the new call type).

@guidezpl What are your thoughts about this? If I misunderstood something or you see any issues, please let me know!

(edit: corrected some statements that were incorrect)