Skip to content

Commit ca28abf

Browse files
authored
Add variantOf to the M3E migration checklist (flutter#195099)
~This can only land **after** flutter/packages#13263 This PR updates the [Material 3 Expressive component migration checklist](https://github.com/flutter/flutter/blob/master/docs/ecosystem/material_ui/Material-3-Expressive-component-migration-checklist.md) so that component migrations resolve the style variant with `<Component>Theme.variantOf`. With `variantOf`, a nested component theme that doesn't set `variant` inherits it from its ancestors instead of resetting its subtree to Material 3. The reference implementation is `IconButtonTheme.variantOf` in flutter/packages#13263. * Section 4: adds `variantOf`, its resolution order, and the reference implementation. * Section 5: uses `<Component>Theme.variantOf(context)` instead of `<Component>Theme.of(context).variant`. * Section 8: adds tests for variant inheritance. * Section 13: lists `variantOf` in the PR description. The [Material 3 Expressive migration skill](https://github.com/flutter/packages/blob/main/.agents/skills/material-3-expressive-migration/SKILL.md) reads this checklist, so agents pick up the change without a skill update. Related to flutter#194414 and https://github.com/orgs/flutter/projects/250 Related to flutter#194414. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.
1 parent 6699e56 commit ca28abf

1 file changed

Lines changed: 45 additions & 5 deletions

File tree

‎docs/ecosystem/material_ui/Material-3-Expressive-component-migration-checklist.md‎

Lines changed: 45 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,47 @@ class IconButtonThemeData with Diagnosticable {
129129

130130
Update the component theme data class support methods, such as `lerp`, `==`, `hashCode`, `debugFillProperties`, etc. Update `copyWith` if the class already has one.
131131

132-
Default null to `StyleVariant.material3` in component behavior.
132+
Add a static `variantOf` method to the component theme widget. It returns the variant that applies at a given `BuildContext`:
133+
134+
1. The first non-null `variant` of the enclosing component themes, starting from the closest one.
135+
2. Otherwise, the `variant` of the component theme in `ThemeData`.
136+
3. Otherwise, `StyleVariant.material3`.
137+
138+
With this, a nested component theme that doesn't set `variant` inherits it instead of resetting its subtree to Material 3. This covers themes that only override `style`, and themes that widgets add internally. For example, `ListTile`, `InputDecorator`, and `AppBar` wrap their children in an `IconButtonTheme` without a variant. An explicit `variant: StyleVariant.material3` still opts a subtree out. Only `variant` is inherited. `style` keeps its current behavior, where the closest theme replaces its ancestors.
139+
140+
Use [`IconButtonTheme.variantOf`](https://github.com/flutter/packages/blob/main/packages/material_ui/lib/src/icon_button_theme.dart) as the reference implementation. [flutter/packages#13263](https://github.com/flutter/packages/pull/13263) added it, along with its docs and tests.
141+
142+
Example:
143+
144+
```dart
145+
class IconButtonTheme extends InheritedTheme {
146+
// ...
147+
148+
static StyleVariant variantOf(BuildContext context) {
149+
InheritedElement? element = context.getElementForInheritedWidgetOfExactType<IconButtonTheme>();
150+
while (element != null) {
151+
// Depend on every theme that is visited, so that a change to any of them
152+
// rebuilds the dependent.
153+
context.dependOnInheritedElement(element);
154+
final StyleVariant? variant = (element.widget as IconButtonTheme).data.variant;
155+
if (variant != null) {
156+
return variant;
157+
}
158+
// Calling getElementForInheritedWidgetOfExactType on the element itself
159+
// would return the same element, so continue the search from its parent.
160+
Element? parent;
161+
element.visitAncestorElements((Element ancestor) {
162+
parent = ancestor;
163+
return false;
164+
});
165+
element = parent?.getElementForInheritedWidgetOfExactType<IconButtonTheme>();
166+
}
167+
return Theme.of(context).iconButtonTheme.variant ?? StyleVariant.material3;
168+
}
169+
}
170+
```
171+
172+
Document the inheritance on the theme data `variant` field, including that an enclosing component theme takes precedence over the one in `ThemeData`. On the theme's `of` method, note that the returned `variant` is only the value of the closest theme and can be null, and point to `variantOf`.
133173

134174
Do not add extra component theme flags unless the component needs them.
135175

@@ -148,8 +188,7 @@ Select defaults using the component theme variant.
148188
Example pattern:
149189

150190
```dart
151-
final StyleVariant effectiveVariant =
152-
<Component>Theme.of(context).variant ?? StyleVariant.material3;
191+
final StyleVariant effectiveVariant = <Component>Theme.variantOf(context);
153192
154193
return switch (effectiveVariant) {
155194
StyleVariant.material3 => _<Component>DefaultsM3(context),
@@ -159,7 +198,7 @@ return switch (effectiveVariant) {
159198

160199
Keep existing Material 3 defaults unchanged.
161200

162-
Ensure M3E defaults apply only when the component theme variant is `StyleVariant.material3Expressive`.
201+
Ensure M3E defaults apply only when `<Component>Theme.variantOf(context)` returns `StyleVariant.material3Expressive`. Use `variantOf` everywhere the component checks the variant. Do not read `<Component>Theme.of(context).variant` directly.
163202

164203
## 6. Add Public Style APIs Only When Required
165204

@@ -200,6 +239,7 @@ Avoid exposing token implementation details in user-facing docs unless the API i
200239
Add focused tests for:
201240

202241
- Component theme `variant` opt-in.
242+
- Variant inheritance through `<Component>Theme.variantOf`: a nested component theme without a `variant` inherits it, an explicit `StyleVariant.material3` opts a subtree out, the `ThemeData` component theme is the fallback, and changing an enclosing theme's `variant` rebuilds the component.
203243
- Generated M3E defaults.
204244
- New style properties.
205245
- Theme-level style defaults.
@@ -334,7 +374,7 @@ Adds Material 3 Expressive support for `<Component>` behind an explicit componen
334374

335375
## Changes
336376

337-
- Adds `<Component>ThemeData.variant`.
377+
- Adds `<Component>ThemeData.variant` and `<Component>Theme.variantOf`.
338378
- Adds new style APIs: `<new style APIs>`.
339379
- Adds `<Component>TemplateM3E`.
340380
- Adds generated defaults in `packages/material_ui/lib/src/generated/<component>_defaults_m3e.g.dart`.

0 commit comments

Comments
 (0)