search

rydmike / flex_color_scheme

A Flutter package to make and use beautiful color scheme based themes.
Other
973 stars 109 forks source link

Documentation improvement #26

Closed bernaferrari closed 2 years ago

bernaferrari commented 2 years ago

You can opt in on using pre-made opinionated widget sub-themes. By opting in, you can for example adjust the border radius on all widgets with a single property to set the same themed border radius on them. Current Flutter SDK widgets are based on the Material 2 guide and use 4 dp corner radius as default on most corners.

I was exploring your great library and there is no word in documentation or anywhere on how to implement this. In your sample there is a toggle to enable round corners everywhere. What is the API called? I can't find it.

bernaferrari commented 2 years ago

Ok, found it. useSubThemes + subThemesData. I think you could add that to documentation :P

rydmike commented 2 years ago

Thanks for the question and feedback @bernaferrari and yes I agree it should and will be better documented.

I actually run into a limitation on how long the readme doc file can be in pub.dev and had to cut back on API overview docs in the readme. There is a 128k char limit on it, after which pub.dev rejects the package. However, since I removed a bunch of other things from version 3, I think I can still fit in a notice on this in the next update too. Always nice with feedback on what pain points are when it comes to API and usage discovery.

Originally I wanted to do the kind of brief API refs links like I have in the flex_color_picker readme: https://pub.dev/packages/flex_color_picker#show-color-names that has API code sample and visual result example and a link to API ref doc as well, but there was not room for it within the readme size limitation imposed by pub.dev.

I plan to move the docs to a separate doc site, like e.g. go_router https://pub.dev/packages/go_router and some other packages do. This will make it easier to maintain and improve the docs without need to release a new package version when docs are updated. Then I can also extend the docs and make them more complete with more code and result examples and links to API refs for each case.

Still, I'm glad you figured it out anyway! 💙

Some API refs on the topic in question:

All APIs do have API reference documentation, but yeah I also think those can be hard to find if one does not not even know where to start looking for it.

Some additional tips for getting deeper into FlexColorScheme.

The default example is like a developers hot reload API playground, with placeholders and extensive explanations of almost every API: https://github.com/rydmike/flex_color_scheme/blob/master/example/lib/main.dart Pretty useful for trying things out and using hot reload to see the impact.

Then the live version of example 5, that I call the Themes Playground https://rydmike.com/flexcolorschemeV4Tut5/#/ is a more interactive version of this. It is very useful since you can interactively play with almost every API setting and then copy paste the API code for the current setup that you are looking at. Even if you don't use this to actually configure and setup FlexColorScheme in your app, it is quite useful to play with to just get up to speed on the options and find the API config for the used options.

image

bernaferrari commented 2 years ago

Thanks. That theme setup was kind of confusing for me because I didn't know what was default and what wasn't. But got it working, thanks!

bernaferrari commented 2 years ago

BTW, kind of unrelated, but I don't want to open another issue.

Is it possible to get FlexSchemeColor.from(ColorScheme) or something like this? I am using the new ColorScheme.seed and got a lot of nice colors for primaryContainer, errorContainer, etc. But FlexSchemeColor overrides it.

rydmike commented 2 years ago

@bernaferrari Yes I plan to add it. I agree and also see how it would be useful, especially when working with the new M3 based ColorScheme.seed constructor, which is still only available on master channel with all the new M3 colors.

I suppose right now what might work (partially), but I did not try, is to create the M3 based color scheme with the ColorScheme.seed pluck out the colors from it that FlexColorScheme does support via its colors now and plug them into FlexColorScheme colors, but yeah that would not return a theme that has all the colors in the new M3 based ColorScheme. Maybe if you apply the missing colors from the seed to the resulting ThemeData's M3 based theme.colorScheme, you would have the colors there then.

I also noticed that there still no Flutter SDK widgets, even on master, that as default use and depends on any of the new extended M3 based colors in ColorScheme on master channel. I'm sure some widgets will use them as defaults at some point. If not, and even if they will, I will probably also look at ways of automatically using the new colors in varying, but consistent ways in your theme based on a few variations that you can easily toggle. But I will have to experiment with that more to see if/how it works and looks.

I have few things I want to add to current v4 for some more M2 theming features. After that my plan is to start prepping for the new real M3 colors and features, since it is coming later this year to stable too. I can keep you in the loop if you are interested in trying it. I will make a new work branch and probably make a dev release of it on pub.dev when it is ready as a preview, hopefully before any of the M3 scheming reaches stable. That dev release would then require using master channel until the APIs it uses reaches stable and it can be released as none dev/preview version.

One challenge will be to see if I can still do it without breaking changes. Still introducing real M3 theming and not only current M2 based M3 look-alike themes, is a good point to do some breaking changes if needed for improvements as well.

rydmike commented 2 years ago

Hi @bernaferrari the readme has via https://github.com/rydmike/flex_color_scheme/pull/30 been updated to include a mention of this and it is no longer hidden in API docs only.

It also includes a first version of the capability to create custom FlexColorSchemes based on a ColorScheme. https://github.com/rydmike/flex_color_scheme/issues/27

There is however not yet an experimental dev release that would support master channel and the new M3 based colors in ColorScheme, but it should not overwrite any colors when basing themes from a ColorScheme, unless you use factories with some of the surface color branding/blending features, then it will overwrite surface and background with computed color branding.

Properties in ColorScheme that are not available in stable should be used and returned as they were in resulting theme ColorScheme too. However, since the package also uses TextTheme that is now completely broken compared to stable in master, using this package with master channel is probably not possible due to breaking changes in master channel. (The TextStyles in TextTheme have been renamed to M3 based names and a few new ones added, without keeping old ones around as deprecated. Imo this probably breaks almost every Flutter app out there, but I read there will be a darfix for it to handle migration of old code, when this is released, I guess we will see how that works)

As mentioned, I do plan to start experimenting with a master channel version and might release a dev version of it as well before major M3 reaches Flutter stable,

Thank you for your feedback and suggestion about also using ColorScheme as base for the custom scheme colors. I added it to version 4.2.0 since I also think it will be useful going forward when using seed and wallpaper dynamic colors as input to FlexColorScheme's theming capabilities.

Closing this documentation improvement and even ColorScheme suggestion as completed.

bernaferrari commented 2 years ago

The TextStyles in TextTheme have been renamed to M3 based names and a few new ones added, without keeping old ones around as deprecated

They are keeping the old ones around, it should take years to deprecate them. The new styles are just => for the old ones.

rydmike commented 2 years ago

Finally on master again and testing with it a bit. Yes I see now when actually in IDE what they did. Added getters to map to the old names, that you cannot mix in constructor with new names.

OK cool this will work nicely. I will just follow and see what happens, at least this will make it easier for me to do some builds and experiments on master. I used to live on it continuously before when Windows desktop support sucked on other channels, but it has been good enough that I have avoided it for the past few months. 😄

I see that the new font geometry is still missing in Typography. I guess there will be something like englishLike2021, dense2021 and tall2021, might even be more since based on M3 spec there should be different geometry on the styles on desktop compared to phones, that don't need the sizes to be as super large as they were before.