TextField and TextFormField can use a MaterialStatesController

[Renzo-Olivares]

This change adds support for a MaterialStatesController in TextField and TextFormField. With this change a user can listen to MaterialState changes in an input field by passing a MaterialStatesController to TextField or TextFormField.

Fixes #133273

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.

[LongCatIsLooong]

(what's the difference between this one and the existing doc template for this in ink_well.dart?)

[Renzo-Olivares]

This one just makes sure to point out the states reported by TextField. { MaterialState.disabled, MaterialState.hovered, MaterialState.error, MaterialState.focused }. ink_well.dart points out MaterialState.pressed which TextField does not report at the moment.

[LongCatIsLooong]

nit: consider linking the part of the material state controller doc that explains that this is not the intrinsic states and if you change the value, future intrinsic states change may overwrite the change?(

[LongCatIsLooong]

Do we actually need an internal states controller if the user didn't supply one? The reason we're adding it is that users want to add listeners to it right?

[Renzo-Olivares]

That is a good point we are currently not using it internally. We do keep track of our _materialState using a private member

flutter/packages/flutter/lib/src/material/text_field.dart

Lines 1215 to 1222 in ff5b5b5

	Set<MaterialState> get _materialState {
	return <MaterialState>{
	if (!_isEnabled) MaterialState.disabled,
	if (_isHovering) MaterialState.hovered,
	if (_effectiveFocusNode.hasFocus) MaterialState.focused,
	if (_hasError) MaterialState.error,
	};
	}

maybe we should just use the controller to track this in one place c1d4cdf.

[LongCatIsLooong]

The purpose of this change is to let developers monitor material states changes, but changing the material states from outside of the TextField class shouldn't be allowed, since the source of the truth is TextFieldState I think?

[Renzo-Olivares]

It does makes sense that TextField would be the source of truth for its material state, but I also see the use-case for being able to programmatically update a TextField's material state to add support for more states.

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: Home()));
}

class PressedInputField extends StatefulWidget {
  const PressedInputField({
    super.key,
    this.style,
    required this.pressed,
    required this.onPressed,
    required this.onReleased,
  });

  final bool pressed;
  final TextStyle? style;
  final VoidCallback? onPressed;
  final VoidCallback? onReleased;

  @override
  State<PressedInputField> createState() => _PressedInputFieldState();
}

class _PressedInputFieldState extends State<PressedInputField> {
  late final MaterialStatesController statesController;
  final TextEditingController controller = TextEditingController(text: 'some text');

  @override
  void initState() {
    super.initState();
    statesController = MaterialStatesController(
        <MaterialState>{if (widget.pressed) MaterialState.pressed});
  }

  @override
  void dispose() {
    statesController.dispose();
    controller.dispose();
    super.dispose();
  }

  @override
  void didUpdateWidget(PressedInputField oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.pressed != oldWidget.pressed) {
      statesController.update(MaterialState.pressed, widget.pressed);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Listener(
      behavior: HitTestBehavior.translucent,
      onPointerDown: (PointerDownEvent event) {
        widget.onPressed?.call();
      },
      child: TextField(
        controller: controller,
        statesController: statesController,
        style: widget.style,
        onTap: () {
          widget.onReleased?.call(); 
        },
      ),
    );
  }
}

class Home extends StatefulWidget {
  const Home({super.key});

  @override
  State<Home> createState() => _HomeState();
}

class _HomeState extends State<Home> {
  bool pressed = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: PressedInputField(
          pressed: pressed,
          style: MaterialStateTextStyle.resolveWith((Set<MaterialState> states) {
            if (states.contains(MaterialState.pressed)) {
              return const TextStyle(color: Colors.white, backgroundColor: Colors.indigo);
            }
            return const TextStyle(color: Colors.teal);
          }),
          onPressed: () {
            setState(() {
              pressed = !pressed;
            });
          },
          onReleased: () {
            setState(() {
              pressed = !pressed;
            });
          }
        ),
      ),
    );
  }
}

I'm okay with holding off on that functionality until it is requested, but I also think when a user updates state through the controller using _myController.update(MaterialState.pressed, true) they might expect that the receiving widget reflects the value change, similar to other controllers like TextEditingController and doing _myController.value = myNewValue.

[LongCatIsLooong]

when a user updates state through the controller using _myController.update(MaterialState.pressed, true) they might expect that the receiving widget reflects the value change, similar to other controllers like TextEditingController and doing _myController.value = myNewValue.

Do you mean if a TextField has focus but if the user calls update(.focused, false) on the controller then the text field should tell its focus node to unfocus? That sounds pretty strange to me.

[LongCatIsLooong]

If the user adds the focused MaterialState after the component loses focus, then the component's visuals will make it appear that the component has the focus.

And if the component regains focus and loses focus again? Should the visual state of the component update as the intrinsic state of the component changes?

• If the answer is no then it sounds like we need an additional switch that the user can turn on to suppress the intrinsic state changes from affecting the visual state
• otherwise the controller will be pretty hard to use on a TextField. For instance the app user can switch the focus to a different component, and to obscure the underlying state change I guess you'll have to listen to the state controller and change the material state back? That usually won't happen until the next frame. Average users may not notice that but that can make tests flaky.

[HansMuller]

If you really wanted to prevent the MaterialStatesController from tracking the textfield's intrinsic focus (or whatever) state you could override the controller's update method. That said, this isn't a use case that has ever come up or seems worth designing for.

[LongCatIsLooong]

Ah ok makes sense. I guess this should be in the documentation?

[HansMuller]

Yes, it's not explained well (at all) and some examples are needed. If you create an issue, you can assign it to me.

[HansMuller]

Updated the MaterialStatesController docs in #134592

[LongCatIsLooong]

nit: consider linking the part of the material state controller doc that explains that this is not the intrinsic states and if you change the value, future intrinsic states change may overwrite the change?(

[LongCatIsLooong]

why does it only update .disabled but not the other properties?

[Renzo-Olivares]

Here and didUpdateWidget seem like the only reasonable places to listen for changes in _isEnabled, while the other state properties like focus (listens to changes in FocusNode) and hover (listens to MouseRegion callbacks) actively listen for changes. I'll also initialize the error state here.

[LongCatIsLooong]

Focus is edge-triggered so you have to set the correct initial value otherwise it won't reflect the correct state until the next time you get notified of a focus state change right? The TextField can be given a FocusNode that may or may not have the focus when initState is called.

[flutter-dashboard]

This pull request executed golden file tests, but it has not been updated in a while (20+ days). Test results from Gold expire after as many days, so this pull request will need to be updated with a fresh commit in order to get results from Gold.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

[HappyEmu]

What is the state of this PR? Are there intentions to take this further?

[Renzo-Olivares]

@HappyEmu Yeah was working on other issues. I'll try to get this un-stale soon.

[LongCatIsLooong]

consider always updating every state in _stateController here in didUpdateWidget. I think that will make it easier to read.

[LongCatIsLooong]

The check and the instance variable don't seem to be necessary?

[LongCatIsLooong]

_hasError doesn't seem to be depending on any inherited widgets?

[Renzo-Olivares]

The RestorableTextEditingController doesn't seem to finish registering the controller by the time _hasError is called which also calls _hasIntrinsicError so when effectiveController.value is accessed there is an assert triggered regarding the controller not being registered for state restoration yet.

[LongCatIsLooong]

You mean it's preventing the material state controller from being fully set-up in initState? Can you make the initialization lazy then?

[Renzo-Olivares]

Making the initialization lazy didn't seem to help, I tried changing the MaterialStatesController to late. Instead I changed _hasIntrinsicError to take into account if there is a pending restore.