[go_router] Add maybePop for safe navigation pops

[muhammadkamel]

Summary

• Adds maybePop to GoRouter, GoRouterDelegate, and GoRouterHelper (context.maybePop()), mirroring Navigator.maybePop and Material BackButton behavior.
• Unlike pop(), maybePop() returns false instead of throwing when nothing can be popped.
• When a pop completes synchronously, maybePop() calls restore() to keep routeInformationProvider in sync with GoRouterDelegate.currentConfiguration (same as pop()).
• Adds test coverage for maybePop, restore(), canPop, mixed Navigator.pop / context.pop flows, and framework BackButton integration.
• Ignores /coverage/ in go_router .gitignore.

Fixes flutter/flutter#115997

Motivation

Apps commonly gate back navigation with if (context.canPop()) context.pop(). Framework widgets like BackButton use Navigator.maybePop(), which is safe but does not sync GoRouter URL/state. maybePop() provides a single GoRouter-native safe pop API:

await context.maybePop();

Test plan

• flutter test packages/go_router/test/maybe_pop_test.dart
• flutter test packages/go_router/test/restore_test.dart
• flutter test packages/go_router/test/extension_test.dart
• flutter test packages/go_router/test/delegate_test.dart
• flutter test packages/go_router/test/router_test.dart

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

Footnotes

1. go_router uses batched release; the changelog entry is in pending_changelogs/add_maybe_pop.yaml instead of editing CHANGELOG.md or pubspec.yaml directly. ↩ ↩²

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request introduces a maybePop method to GoRouter, GoRouterDelegate, and GoRouterHelper to support popping routes without throwing exceptions when the stack is empty, mirroring Navigator.maybePop. It also adds extensive tests covering the new method, state restoration, and integration scenarios. The review feedback suggests adding a state.mounted check within the asynchronous loop in GoRouterDelegate.maybePop to prevent potential exceptions if a navigator is unmounted during execution.

[muhammadkamel]

Hi @chunhtai @hannah-hyj

Would appreciate a review when you have time. Thanks!

[stuartmorgan-g]

@muhammadkamel While waiting for full review, please take a look at the current docs for version/CHANGELOG updates; this package now uses batched release, which follows a different process for updating those PRs.

[chunhtai]

Also please do not remove the pre review checklist

[muhammadkamel]

@chunhtai

Could you please take another look?

[chunhtai]

This doesn't feel right

This will only return false if all navigators in the widget tree return false. maybePop shouldn't be this aggressive.

I actually not entirely sure what is the correct behavior here. maybePop is scoped to consult only one navigator. but in GoRouter, there is a group of navigators

[muhammadkamel]

Thanks for the feedback — agreed that walking every navigator was too aggressive.

maybePop now consults only the first navigator from _findCurrentNavigators(), matching Navigator.maybePop's single-navigator scope. If that navigator has nothing to pop, we return false and do not fall through to parents (unlike popRoute, which still walks the stack for system back).

One intentional consequence under shell routes: canPop() can be true while maybePop() returns false, because canPop/pop consider any navigator that can pop, while maybePop only asks the current one. Docs and tests now call that out explicitly — please let me know if you'd rather have maybePop follow pop()'s multi-navigator selection instead.