[Proposal] Router api allow to replace state

[maRci002]

Use case

Imagine a situation where user wants to navigate to / then the app starts to check authentication status which is currently unknown (neither loggen in nor logged out) so I don't want to replace current url however I want to put some state in history (for instance to detect forward / backward actions).

In JS world History.replaceState's 3. parameter url is optional to achive this kind of behavior or just by passing '', null, undefined
as the third parameter.

Currently RouteInformationParser.restoreRouteInformation can return null to indicate not to update history.

This may return null, in which case the browser history will not be updated and state restoration is disabled.

RouteInformation's location property can also be null however using null will throw exception (what is the meaning of null?).

If I pass an empty string '' to RouteInformation.location then it will cause unexpected results like this:

1. User opens app /
2. RouteInformationParser.restoreRouteInformation returns RouteInformation(location: '', state: state) since authentication status is unknown
3. browser replaces the state
4. authentication status changed so RouteInformationParser.restoreRouteInformation returns RouteInformation(location: '/', state: state)
5. browser history stack contains two '/' instead of one.

Proposal

If you look at PlatformRouteInformationProvider's current implementation:

  @override
  void routerReportsNewRouteInformation(RouteInformation routeInformation, {RouteInformationReportingType type = RouteInformationReportingType.none}) {
    final bool replace =
      type == RouteInformationReportingType.neglect ||
      (type == RouteInformationReportingType.none &&
       _valueInEngine.location == routeInformation.location);
    SystemNavigator.selectMultiEntryHistory();
    SystemNavigator.routeInformationUpdated(
      location: routeInformation.location!,
      state: routeInformation.state,
      replace: replace,
    );
    _value = routeInformation;
    _valueInEngine = routeInformation;
  }

1. Documentation should clarify what null means in RouteInformation.location.
2. _value / _valueInEngine shouldn't save RouteInformation if it's location is '' just copy the old one with the new state.
3. final bool replace should handle specials cases like when RouteInformation.location is '' or null.

This is a possible implementation:

  @override
  void routerReportsNewRouteInformation(
    RouteInformation routeInformation, {
    RouteInformationReportingType type = RouteInformationReportingType.none,
  }) {
    final isEmptyLocation = routeInformation.location == null || routeInformation.location == '';

    final replace = type == RouteInformationReportingType.neglect ||
        (type == RouteInformationReportingType.none && (isEmptyLocation || _valueInEngine.location == routeInformation.location));
    SystemNavigator.selectMultiEntryHistory();
    SystemNavigator.routeInformationUpdated(
      // in case of [isEmptyLocation] we can also use old location [_valueInEngine.location!]
      location: isEmptyLocation ? '' : routeInformation.location!,
      state: routeInformation.state,
      replace: replace,
    );

    // TODO: _valueInEngine.copyWith(state: routeInformation.state) would be much nicer
    final newRouteInformation = isEmptyLocation
        ? RouteInformation(
            location: _valueInEngine.location,
            state: routeInformation.state,
          )
        : routeInformation;

    _value = newRouteInformation;
    _valueInEngine = newRouteInformation;
  }

[exaby73]

Hello @maRci002. Thank you for raising this proposal. Labeling for further insights from the team

[goderbauer]

cc @chunhtai