[go_router] Support for top level onEnter callback.

[omar-hanafy]

Description:
This PR introduces top level onEnter callback in RouteConfiguration to allow developers to intercept and conditionally block navigation based on incoming routes. It adds an example (top_level_on_enter.dart) demonstrating its usage, such as handling referral code from /referral.

What This PR Changes:

• Adds the onEnter callback (typedef OnEnter) to intercept route navigation before processing.
• Implements logic for onEnter in GoRouteInformationParser.
• Updates RouteConfiguration to include the onEnter callback.
• Adds a new example, top_level_on_enter.dart, to demonstrate the feature.
• Adds a test case to verify the onEnter callback functionality.

Simple usage example:

final GoRouter router = GoRouter(
  onEnter: (context, state) {
    // Save the referral code (if provided) and block navigation to /referral.
    if (state.uri.path == '/referral') {
      saveReferralCode(context, state.uri.queryParameters['code']);
      return false;
    }

    return true; // Allow navigation for all other routes.
  },
  routes: [ ... ],
);

Impact:
Enables developers to implement route-specific logic, such as support for handling action-based deep links without navigation (160602)

Pre-launch Checklist:

• I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
• I read the [Tree Hygiene] page, which explains my responsibilities.
• I read and followed the [relevant style guides] and ran the auto-formatter. (Unlike the flutter/flutter repo, the flutter/packages repo does use dart format.)
• I signed the [CLA].
• The title of the PR starts with the name of the package surrounded by square brackets, e.g., [go_router].
• I [linked to at least one issue that this PR fixes] in the description above.
• I updated pubspec.yaml with an appropriate new version according to the [pub versioning philosophy], or this PR is [exempt from version changes].
• I updated CHANGELOG.md to add a description of the change, [following repository CHANGELOG style], or this PR is [exempt from CHANGELOG changes].
• 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.

[omar-hanafy]

Hi @chunhtai,

This PR introduces a top-level onEnter callback, addressing critical gap in go_router’s handling of deep links and redirect customizations. It allows developers to intercept routes, block navigation, or implement custom logic.

Given its potential impact, your feedback would be greatly appreciated.

Thank you for your time!

[chunhtai]

If this is more powerful, we should deprecate redirect. fyi there is also this https://docs.google.com/document/d/1L940WGrM1YJ8BkJEpNd67fUqoqC6OsTfch4eH86E0xU/edit?resourcekey=0-9oxsWU1tLpAACTUXyNjpkA&tab=t.0

[omar-hanafy]

Hi @chunhtai Thanks for sharing the design doc! After reviewing it, I have some thoughts on how we can potentially combine approaches:

1. For the current PR, we could enhance the onEnter callback signature to match the guard pattern:

typedef OnEnter = bool Function(
  BuildContext context,
  GoRouterState currentState,
  GoRouterState nextState
);

2. This would make it easier to later migrate to the guard-based approach while solving the immediate need. The boolean return could map to Resolution.next (true) and Resolution.stop (false).

3. The guard system looks like a more complete solution for the long term, but the current onEnter approach could serve as a simpler solution that:

   • Handles the action-based deeplinks case.
   • Provides access to router operations.
   • Allows splash screen handling through router access.
   • Maintains backward compatibility.

Would you prefer, I update the PR to use this enhanced signature?