Description

Prior to this change, the MaterialPage and CupertinoPage would take a builder, which was a footgun:

class _KeepsStateTestWidgetState extends State<KeepsStateTestWidget> {
  String _subpage = 'subpage';

  @override
  Widget build(BuildContext context) {
    return CupertinoApp(
      home: Navigator(
        key: widget.navigatorKey,
        pages: <Page<void>>[
          const CupertinoPage<void>(builder: (BuildContext context) => Text('home')),
          if (_subpage != null) CupertinoPage<void>((BuildContext context) => Text(_subpage)),
        ],
        onPopPage: (Route<dynamic> route, dynamic result) {
          if (!route.didPop(result)) {
            return false;
          }
          setState(() {
            _subpage = null;
          });
          return true;
        },
      ),
    );
  }
}

When the second page is transitioning out, _subpage is set to null. Because the Navigator is rebuild, it would rebuild all its routes as well with that the builder of the second executes again, rebuilding itself with _subpage == null, which is not what people want.

This PR changes the API of CupertinoPage and MaterialPage. Instead of taking a builder, it takes a prebuild child widget to avoid this problem.

This PR also removes the CustomBuilderPage and TransitionBuilderPage. We can come up with a version of them that doesn't rely on builders in the future.

Related Issues

Fixes #66695.

Tests

I added the following tests:

• Updated existing tests
• Added tests to verify that pages don't loose their state when popped.

Checklist

Before you create this PR, confirm that it meets all requirements listed below by checking the relevant checkboxes ([x]). This will ensure a smooth and quick review process.

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I signed the CLA.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I updated/added relevant documentation (doc comments with ///).
• All existing and new tests are passing.
• The analyzer (flutter analyze --flutter-repo) does not report any problems on my PR.
• I am willing to follow-up on review comments in a timely manner.

Breaking Change

Did any tests fail when you ran them? Please read Handling breaking changes.

• No, no existing tests failed, so this is not a breaking change.
• Yes, this is a breaking change. If not, delete the remainder of this section.
  • I wrote a design doc: https://flutter.dev/go/template Replace this with a link to your design doc's short link
  • I got input from the developer relations team, specifically from: Replace with the names of who gave advice
  • I wrote a migration guide: https://flutter.dev/go/breaking-changes-template Replace this with a link to a pull request that adds the migration guide to https://flutter.dev/docs/release/breaking-changes