Add migration guide for page apis

[chunhtai]

migration guide for flutter/flutter#137792

Presubmit checklist

• This PR doesn’t contain automatically generated corrections (Grammarly or similar).
• This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn’t use i.e. or e.g., and it avoids I and we (first person).
• This PR uses semantic line breaks of 80 characters or fewer.

[flutter-website-bot]

Visit the preview URL for this PR (updated for commit 594455f):

https://flutter-docs-prod--pr10523-page-apis-re-iomugcxy.web.app

[sfshaza2]

Can you add this breaking change to the index file?

[parlough]

Could you add a word or two to be more specific here, as the mentioned APIs could have other breaking changes in the future. Thanks!

[sfshaza2]

good point

[chunhtai]

all done

[sfshaza2]

lgtm

[aliyazdi75]

Hi @chunhtai,

Since this api is deperecated, I think it's better to mention to use onPopInvoked to use the result, something like this:

class CustomAppPage<T> extends Page<T> {
  const CustomAppPage({
    super.key,
    super.onPopInvoked,
    required this.child,
  });

  final Widget child;
}

CustomAppPage(
    key: ValueKey(route),
    onPopInvoked: (didPop, result) =>
        _routerState.popResult.complete(result),
    child: CustomPage(),
),