Widget state properties

[MitchellGoodwin]

Fixes #138270.

Moves the majority of the logic of MaterialStateProperties down to the widgets layer, then has the existing Material classes pull from the widgets versions.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

[goderbauer]

Wondering why this is the only one that isn't a typedef?

[MitchellGoodwin]

It's because of the toString message saying specifically "MaterialStatePropertyAll". I was unsure if it was important if that backwards compatibility was preserved, so I left it as it's own thing.

[goderbauer]

Do any customer_tests or anything in google3 fail if the toString message is changed? If nothing fails, it wouldn't be considered a breaking change under our policy and we should simplify this.

[goderbauer]

We should probably deprecate the Material-only ones since it is going to be confusing to have the same concept under two different names.

[goderbauer]

We should also add a flutter fix to make it easier for people to migrate to the widget version.

[MitchellGoodwin]

I think that'd be cleaner. The only issue is if Material deviates from what could be considered generic, non-specific we would need to add back in MaterialStates after deprecating it.

Which I don't feel like is too likely? So maybe it would be better to pull the trigger and deprecate the one's that can't be typedefs.

[goderbauer]

I am leaning towards deprecating the Material* ones to avoid the confusion of having two names for the same concept. If Material evolves, I think we'd want to evolve the underlying Widget* ones to be able to handle those cases as well. But lets also get the input from our material and deprecation experts (@HansMuller @Piinks) on this.

[Piinks]

I think the goal was to allow material to have its own specific states, while the widget base concept was kept more generic. So, MaterialState would inherit all the basic states from WidgetState, and then have some of its own material-specific ones.

However, I am not sure how this is possible with this current proposal. How would we add a material-specific state to MaterialState with this change?

Maybe we could consider scrolledUnder as material-specific and remove it from the widgets states to put it here in the material states as a proof of concept.

[MitchellGoodwin]

I'm not sure how possible it is to take the values from one enum to create an extended version while making it easy to have them be somewhat interchangeable, without turning both into a class that emulates enums. It looks like the Dart team is against the idea: dart-lang/language#2733.

I think in the long run, even if there are Material specific values, it would be helpful to still put them in the Widgets layer. There would likely be use cases for all of them in Cupertino by itself, but it would also make adaptive work smoother. The Material specific logic can be in functions like MaterialStateOutlineInputBorder that would have apply Material styling on top of the shared WidgetState enum.

[Kypsis]

From a custom design system pov and taking future proofing into account would be nice if the WidgetState would be extensible. But what is already in the enum is probably more than enough for the majority of the design systems out there.

[knopp]

I think in the long run, even if there are Material specific values, it would be helpful to still put them in the Widgets layer

This already happened here and I think it's this is a concerning outcome. We now have material specific concepts in a package that was previously agnostic to widget sets and design systems.

[goderbauer]

inherited? I think this should probably say what you said on the other one that they can just be used interchangable?

[goderbauer]

Can this be done with a typedef?

[MitchellGoodwin]

Same as elsewhere, I was worried about the debugFillProperties returning differently.

[goderbauer]

Same as my comment above.

[MitchellGoodwin]

Converting this mixin into a typedef seems like a pretty big breaking change. It's methods (setMaterialState, addMaterialState, `removeMaterialState, etc.) throw errors if this is just converted into a typedef. I'm marking this as deprecated and seeing what can be helped along with a flutter fix.

[Piinks]

I think the goal was to allow material to have its own specific states, while the widget base concept was kept more generic. So, MaterialState would inherit all the basic states from WidgetState, and then have some of its own material-specific ones.

However, I am not sure how this is possible with this current proposal. How would we add a material-specific state to MaterialState with this change?

Maybe we could consider scrolledUnder as material-specific and remove it from the widgets states to put it here in the material states as a proof of concept.

[Piinks]

For the tests in the material directory, should they use MaterialState instead of WidgetState since the material one should be a subclass of the widget one?

[MitchellGoodwin]

Right now, MaterialStateMouseCursor is a typedef, which because the widget version has an overridden get debugDescription, it is returning "WidgetStateMouseCursor" for both. Which means it should probably be a subclass instead.

[HansMuller]

If we make the MaterialStates a distinct type from WidgetStates developers will not be able use them interchangeably. That might be counterproductive and if we don't have a important use case to motivate the distinction it might be easier to just have one definition of the set of valid component states.

[MitchellGoodwin]

Converting to a draft. Will make a branch off of this one to test flutter fixes.

[knopp]

This now ties widgets package to a specific design system. Some design system have tri-state checkboxes for example and the WidgetState enum is not generic enough to represent. It even links to material documentation. This feels like a mistake.

[rydmike]

@Kypsis, I just found this discussion when I saw the merge. Thank you! I could not agree more on everything you said and concluded in your two posts.

---

About flex_color_scheme that you mention too, it was basically born because I did not want to deal with the complexities and verbosity of theming Material widgets every time. Well, theming them to the extent that Material widgets can be themed, which like you say is very inconsistent and often limited. Loved your examples of that! 😄

• FlexColorScheme started as just a simpler factory to make reasonable and nice looking ThemeData and ColorScheme, and from it use custom color mappings to component themes. Quick and easy customization of border radius globally and per component is also a big part of it. These simple things, that many devs seem to struggle with, can get many designs "close enough", sure not big custom design requirements like yours, since it is still 100% limited by what ThemeData can do. Still close enough for "most" devs design needs and use cases. I guess that contributed to its popularity. Then later FCS also got a visual config tool Themes Playground, so I and its other users don't have to remember FCS own APIs. Which over time has become a bit, well, let's say it has its own none breaking legacies too 😄

• FCS also later got features for adaptive themes, and custom seeded color scheme configs. So if you like, you can keep default M3 styles, radius and color tinted surface results, typically on Android, but get another more agnostic style on other platforms, often by removing tints, using a different radius, etc. Sure those pesky elevation tints (that you can remove with FCS on all or desired platforms) are going away now anyway, in favor fixed surface colors with various levels primary chroma mixed into them. End result will still be that users will want an adaptive response where those color mappings with their primary color chroma baked in, are not so aggressive (M3 opinionated) on other platforms.

I have also as started thinking about a next gen tool for styling and theming Flutter apps. The Figma integrations you mention is something I'm also considering. I have looked at Mix too, it does a lot of things right.

Still I digress (as usual), I just wanted to say I know very well where you are coming from, and that I also think that a more holistic approach to component styling and building is desperately needed in Flutter.

---

Going back to other feedback about WidgetState, e.g. just now by @knopp, I also suspect this is not generic enough and it feels a bit like a quick band-aid fix, sure it will help now, but it may come back to haunt us with ghost pains later. I think @Hixie captured many of those concerns as well, in all the earlier discussions above.

Another thing that was mentioned in comments above was that using MaterialState is seen as very challenging and complicated, thus WidgetState is too. It is is even seen as a hurdle by many devs. Not sure what could be done about it, but I do agree that it is "a bit" complicated and does not look very pretty when used. The order in which you resolve the states also impact the end result, which may add to the usage confusion.

Another interesting thing is that assigning a custom MaterialState in any ThemeData component theme property breaks the equality check of ThemeData. Depending on how you use ThemeData, this can cause extra rebuilds of MaterialApp. This is demonstrated here: #89127 (comment)

[knopp]

I've read the conversation above I am a bit confused. @Hixie has raised some good points but then, after a meeting (?) the PR got approved without any of those points being addressed.

For reference, this is state of a button in our design system:

enum SelectionState {
  on,
  off,
  mixed,
}

class ButtonState {
  ButtonState({
    this.selected = SelectionState.off,
    this.enabled = false,
    this.focused = false,
    this.hovered = false,
    this.pressed = false,
    this.tracked = false,
  });

  /// Determines selection state of the control.
  final SelectionState selected;

  /// Control is enabled and can be interacted with.
  final bool enabled;

  /// Control has keyboard focus.
  final bool focused;

  /// Control is being hovered over by a pointer.
  final bool hovered;

  /// Control is being pressed. When pointer is released without leaving the
  /// control, the control will receive a tap event.
  final bool pressed;

  /// Control is receiving pointer events but the pointer may or may not be
  /// hovering over the control.
  final bool tracked;

  ...
}

It's pretty simple as far as states go, but even then it cannot be represented by WidgetState because of indeterminate selection state. If a standard desktop checkbox can't be represented by WidgetState does it really belong to the base widgets package?

On top of that WidgetState has scrolledUnder, which was clearly added there with material in mind.

Btw, having simple class with bunch of properties is much nicer to use than a set of enums. But that's not the main point.

I'm not against having widget state represented in widgets package, but it shouldn't be a carbon copy of MaterialStateProperties.

[rydmike]

I've read the conversation above I am a bit confused. @Hixie has raised some good points but then, after a meeting (?) the PR got approved without any of those points being addressed.

There was/is also the Widget State Properties document, but it seems like it was abandoned without much further discussion or elaboration.

[benthillerkus]

I personally like MaterialState (though only in combination with flutter_hooks and ISet from fast_immutable_collections).

Maybe instead of tying the Set to a predefined Enum of possible values, instead something like

class WidgetState {
  final ISet<WidgetStateAspect> state;
}

class WidgetStateAspect {}

class Hovered extends WidgetStateAspect {}
...

could be possible?

That way it'd be easy to extend with design system specific details -- and some metadata or substate could actually be put inside of these instances.

[Kypsis]

@rydmike Massive respect for what you have accomplished with FCS and your tireless work in explaining how to use it on Twitter etc to solve the pain points of working around Flutters Material theming. But there is a corner of my mind that screams at the sheer absurdity that this is even necessary.

@knopp In the absence of meaningful big picture pragmatic solutions from Flutter team on the overall topic, one will accept the small wins regardless of the right or wrong of the implementation details. At least the needle is moving.

Even if we as Flutter developers have gotten accustomed to the "Stockholm syndrome" it does not objectively mean that things are in a good place. I would argue that almost a decade later and Flutter still does not quite grasp the greater UI ecosystem it is part of and how to consume what other parts (mainly design) provide. If you look at the very earliest Flutter Github issues where the discussions mainly flowed between Flutter team members, the general ignorance of the UI problem space and not understanding the greater context paints a hilariously bad picture. Almost like a story of non-UI developers best guesses and thought experiments without evidence of deeper insights based on industry "in the trenches" experience and battle scars. And on the meta level this has persisted to the year 2024 (yes things are getting "better" but only by taking baby steps). Somehow Flutters competitors don't seem to suffer from this particular malady.

So in conclusion "A bird in hand is worth two in the bush".

[goderbauer]

Thanks for all the feedback about WidgetStateProperties. I would like to point out that they are just a building block that the widget library offers. If they don't work for your design language, you don't have to expose them in your API and you can (continue to) use whatever suits your needs. They have been battle-tested in the material library for years and have solved problems that we are now also facing in the Cupertino library, hence this generalization to use the same mechanism for the same problem.

Specifically about the tristate checkbox: The material Checkbox has offered tristate support for years and the material/widget states AFAIK haven't been an obstacle for that.

[MitchellGoodwin]

There are two main goals to moving state properties down to the widgets layer:

1. Supporting adaptive work. Cupertino has had no concept of MaterialState properties, and no way to get them. Moving state properties down to the widgets layer lets Material pass it's logic to Cupertino directly without having to make best guesses in what a MaterialState.all property should be.

2. Making state property logic available to package authors that want it, but do not want to use Material. This is from feedback given to the team. If developers want to use tools we already have to build on top of flutter, we don't see a reason to stop them.

There is currently no plan to use WidgetState anywhere in the base widgets, especially ones that already exist. Ideally, we'd come up with a better way to design the API for WidgetState before that happens. The negative feedback about MaterialState/WidgetState is something that we do take seriously and we do want to find a more graceful solution to it. This is not the end of improvements to WidgetState.

On MaterialState/WidgetState being Material focused: before starting this I tried to find other design systems ideas of a widgets interactive state to see if there's a reason not to make it agnostic to Material. None of the properties are, at their core, Material specific. I think if they were presented fresh under a different name outside of Flutter, nobody would go "Hey aren't these just Material design?" The weirdest one being scrolledUnder, which definitely was added with Material in mind, but I can think of one obvious place where it could be used in Cupertino, which is with the sliver navbar widget.

[knopp]

Specifically about the tristate checkbox: The material Checkbox has offered tristate support for years and the material/widget states AFAIK haven't been an obstacle for that.

Right. But that's only because the checkbox MaterialState doesn't distinguish between selected and mixed. Both are "selected". As far as I can tell you can't have a different color for mixed vs selected state for example. (I'll be happy to get corrected if I'm wrong about this).

If they don't work for your design language, you don't have to expose them in your API and you can (continue to) use whatever suits your needs.

I don't think "just don't use" is a fair argument here. With this change the Widgets package now takes over material specific concepts. This has not been the case before and goes in a direction that to me is quite concerning.

[knopp]

Supporting adaptive work. Cupertino has had no concept of MaterialState properties, and no way to get them. Moving state properties down to the widgets layer lets Material pass it's logic to Cupertino directly without having to make best guesses in what a MaterialState.all property should be.

I guess this is my issue here: In my opinion just because something is useful for both material and Cupertino it does not necessarily mean it should go into widgets layer. Flutter ecosystem goes beyond material and Cupertino. (sidenote - I'd love to see these becoming separate packages, and I know I'm not the only one, but that's for another conversation).