nit: extra blank line

nit: most other examples have the main at the top of the file.

I assume that it's up to the caller to make sure that they don't call update on a MaterialStateController unless they are currently allowed to rebuild this widget (either inside this widget or a parent currently building)?

Also, maybe checking to see if this widget is still mounted might be helpful? Although I guess we're unregistered in dispose, so it probably can't happen.

Yes, it must be safe to call setState() when the ButtonStyleButton's controller's states are changed.

If setState() is called at the wrong time the error message is pretty self-explanatory

I don't think you want to call dispose on this unless you allocated it here. Isn't the caller responsible for calling dispose if they supply one?

There's a pattern I use for this in several places:

class FooManager {
  @mustCallSuper
  void dispose() {}
}

class Foo extends StatefulWidget {
  const Foo({this.manager});

  final FooManager? manager;

  @override
  State<Foo> createState() => _FooState();
}

class _FooState extends State<Foo> {
  FooManager? _internalManager;
  FooManager get manager => widget.manager ?? _internalManager!;

  @override
  void initState() {
    super.initState();
    if (widget.manager == null) {
      _internalManager = FooManager();
    }
  }

  @override
  void dispose() {
    _internalManager?.dispose();
    super.dispose();
  }

  @override
  void didUpdateWidget(Foo oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.manager != oldWidget.manager) {
      if (widget.manager != null) {
        _internalManager?.dispose();
        _internalManager = null;
      } else {
        _internalManager ??= FooManager();
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return const SizedBox();
  }
}

And then just call the manager getter in the rest of the State code.

controller?.dispose(); disposes the button's AnimationController, not its MaterialStatesController. I wasn't disposing the statesController, but I suppose I should.