How does the App navigation work

[Dev-Micah]

Can't seem to get the applications navigation flow have tried to check the TreeNav Library but didn't get it right.
Also about the State do i have to pass the authrepository in it.

[tunjid]

The app manages navigation as state, using a soft fork of Navigation 3 bc Navigation 3 is not KMP compatible yet. This should be resolved with compose 1.9.

A high level overview of the navigation semantics are explained in this video.

Ultimately, it makes it easy to build out navigation for multiple screen sizes at once.

The root navigation type is a MultistackNav, managed by the NavigationStateHolder typealias. The NavigationStateHolder holds an instance of a MultiStackNav in memory, and every time it changes, it's persisted to disk in the SavedStateDataStore.

To navigate in the app, a navigation action is sent from the a ViewModel, and the ViewModel sends a navigation mutation to the NavMutator. A navigation mutation is a lambda with a MultiStackNav as a receiver. It describes what change to make to the MultiStackNav. Any navigation action ultimately changes the current value of MultiStackNav in the NavigationStateHolder.

For example in the NavigationMutator there are two constants:

private val SignedInNavigationState = MultiStackNav(
    name = "signed-in-app",
    stacks = listOf(
        AppStack.Home,
        AppStack.Search,
        AppStack.Messages,
        AppStack.Notifications,
    ).map(AppStack::toStackNav)
)

private val SignedOutNavigationState = MultiStackNav(
    name = "signed-out-app",
    stacks = listOf(
        AppStack.Auth.toStackNav()
    )
)

Signing in changes the navigation state SignedInNavigationState. Signing out changes it to an instance of SignedOutNavigationState.

In the UI layer, navigation happens with the ViewModel. Take the home screen for example. Its ViewModel constructor looks like this:

class ActualHomeViewModel(
    ...
    navActions: (NavigationMutation) -> Unit,
    ...
) 

A NavigationMutation has the following signature:

typealias NavigationMutation = NavigationContext.() -> MultiStackNav

Its a function that reads the current navigation context, and returns a new MultiStackNav instance. A NavigationContext is the following:

interface NavigationContext {
    val navState: MultiStackNav
    val String.toRoute: Route
    fun Route.encodeToQueryParam(): String
}

It allows for reading the current navigation state, and for converting a url string to a fully defined Route.

The ViewModel takes navigation actions which looks like this:

    sealed class Navigate : Action(key = "Navigate"), NavigationAction {
        data class To(
            val delegate: NavigationAction.Destination,
        ) : Navigate(), NavigationAction by delegate
    }

All NavigationAction.Destinations in the app are represented using url strings. For example:

fun profileFollowersDestination(
    profileId: ProfileId,
): NavigationAction.Destination = pathDestination(
    path = "/profile/${profileId.id}/followers",
    referringRouteOption = ReferringRouteOption.Current
)

fun signInDestination(): NavigationAction.Destination = pathDestination(
    path = "/auth",
)

So on the home screen, if a guest user wants to sign in, routing to the sign in screen looks something like this:

    PostInteractionsBottomSheet(
        ...,
        onSignInClicked = {
            actions(
                Action.Navigate.To(signInDestination())
            )
        },
    )

All the app does, is either push or pop these destinations unto the MultiStackNav. In the NavigationStateHolder, the above call is routed here:

        internal data class ToRawUrl(
            ...
        ) : Destination() {
            override val navigationMutation: NavigationMutation = {
                routeString(
                    path = path,
                    queryParams = miscQueries + mapOf(
                        "model" to models.map(UrlEncodableModel::toUrlEncodedBase64),
                        "sharedElementPrefix" to listOfNotNull(sharedElementPrefix),
                        "avatarSharedElementKey" to listOfNotNull(avatarSharedElementKey),
                        referringRouteQueryParams(referringRouteOption),
                    )
                ).toRoute
                    .takeIf { it.id != currentRoute.id }
                    ?.let(navState::push) // <--- This is where pushing happens.
                    ?: navState
            }
        }