[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!

[omar-hanafy]

Hi @chunhtai, Following up on this PR. I've updated the implementation to:

1. Enhance OnEnter signature to include current and next state:

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

2. Deprecate top-level redirect in favor of OnEnter.

Let me know if you'd like any adjustments to this approach.

[omar-hanafy]

Hi @chunhtai,

I've expanded the OnEnter callback again to include a GoRouter parameter to handle early-stage navigation. This addition addresses an edge case where navigation is needed before the InheritedGoRouter is available in the widget tree (particularly during initial app launch and deep linking).

The implementation:

• Adds GoRouter as the fourth parameter to OnEnter
• Internally adds new _fallbackRouter to be passed to the OnEnter callback when goRouter instance is not yet available through context.