feat(router): BREAKING - router.push now uses PUSH navigation

[marklawlor]

Why

router.push() should always most history forwards. However we are currently using the NAVIGATE action which may move history backwards if the screen is in history and the closest navigator is a Stack.

Adds router.navigate for when users wish to opt out of this behaviour.

Fix: expo/router#758
Fix: expo/router#741

Keeping this in draft until #24598 is merged

How

This changes router.push() to a PUSH action if the lowest nested navigator is a stack and shared between the old & new routes. Otherwise it defaults back to NAVIGATE.

Test Plan

Included test case

Checklist

• Documentation is up to date to reflect these changes (eg: https://docs.expo.dev and README.md).
• Conforms with the Documentation Writing Style Guide
• This diff will work correctly for npx expo prebuild & EAS Build (eg: updated a module plugin).

[marklawlor]

Change name to pushOrPop

[marklawlor]

Add navigation event types (replace/push/pushOrPop) to <Link />

[hasanaktas]

Is there an estimated time for release?

[marklawlor]

Most likely v3, as this is a breaking change.

[EvanBacon]

Update the docs too and add a guide about differences between push / pushOrPop.

[kennethstarkrl]

@marklawlor The push issue still exists for me after this change in v3.
Doing a router.push() to the same route with different params changes the url with the new params, but the page doesn't change.

I commented out the following from /expo-router/build/global-state/routing.js getNavigateAction() and now push is working and navigates as I expected to.

if (route.state && routesAreEqual && currentRoute.state) {
    return getNavigateAction(route.state, currentRoute.state, type);
}

My guess is that since only the route params changed, all the routes and states are equal. Might need an additional check to see if the params are equal as well.

I modified it adding a params are equal check and it seems to be working
(not entirely sure if this is optimal or correct)

function getNavigateAction(state, parentState, type = 'NAVIGATE') {

    const route = state.routes[state.routes.length - 1];

    const currentRoute = parentState.routes.find((parentRoute) => parentRoute.name === route.name);
    const routesAreEqual = parentState.routes[parentState.index] === currentRoute;
    const paramsAreEqual = rewriteNavigationStateToParams(parentState).params === rewriteNavigationStateToParams(state).params;
    // If there is nested state and the routes are equal, we should keep going down the tree
    if (route.state && routesAreEqual && currentRoute.state && paramsAreEqual) {
        return getNavigateAction(route.state, currentRoute.state, type);
    }
    // Either we reached the bottom of the state or the point where the routes diverged
    const { screen, params } = rewriteNavigationStateToParams(state);
    if (type === 'PUSH' && parentState.type !== 'stack') {
        type = 'NAVIGATE';
    }
    else if (type === 'REPLACE' && parentState.type === 'tab') {
        type = 'JUMP_TO';
    }
    return {
        type,
        target: parentState.key,
        payload: {
            name: screen,
            params,
        },
    };
}