Navigation & coupeling

[shaharKeisarApps]

I'm currently exploring the Circuit UI framework and am interested in understanding how to ensure that my screens are decoupled from the navigation logic, similar to how it's done in the NowInAndroid sample which uses Jetpack Compose Navigation's NavHost and routes.

In the NowInAndroid sample, screens themselves don't need to know anything about navigation. They just call a function like onTopicClick, and the function handles the navigation. Here's the relevant code snippet:

/**
 * Top-level navigation graph. Navigation is organized as explained at
 * https://d.android.com/jetpack/compose/nav-adaptive
 *
 * The navigation graph defined in this file defines the different top level routes. Navigation
 * within each route is handled using state and Back Handlers.
 */
@Composable
fun NiaNavHost(
    appState: NiaAppState,
    onShowSnackbar: suspend (String, String?) -> Boolean,
    modifier: Modifier = Modifier,
    startDestination: String = forYouNavigationRoute,
) {
    val navController = appState.navController
    NavHost(
        navController = navController,
        startDestination = startDestination,
        modifier = modifier,
    ) {
        // TODO: handle topic clicks from each top level destination
        forYouScreen(onTopicClick = {})
        bookmarksScreen(
            onTopicClick = navController::navigateToTopic,
            onShowSnackbar = onShowSnackbar,
        )
        searchScreen(
            onBackClick = navController::popBackStack,
            onInterestsClick = { appState.navigateToTopLevelDestination(INTERESTS) },
            onTopicClick = navController::navigateToTopic,
        )
        interestsGraph(
            onTopicClick = { topicId ->
                navController.navigateToTopic(topicId)
            },
            nestedGraphs = {
                topicScreen(
                    onBackClick = navController::popBackStack,
                    onTopicClick = {},
                )
            },
        )
    }
}

I would like to know how I could achieve similar decoupling using Circuit. I want my screens to just call a function for navigation events, and the function itself to handle the navigation. Is this possible with Circuit? If so, I'd appreciate guidance or advice on how to implement this.

In addition, Is there anything else I should know about handling navigation in Circuit, especially in comparison to Jetpack Compose Navigation?

Thank you!

[ZacSweers]

Take a look at our navigation docs: https://slackhq.github.io/circuit/navigation/

Generally, all presenters need to know is the Screen it's going to and circuit will connect the rest.

You can also implement a custom navigator and push your own logic inside of it, such as writing a navigation DSL

[shaharKeisarApps]

So what should I do in the case where I have a screen that should be able to appear anywhere in the application - for example, a password screen, which will return a true/false answer..

[ZacSweers]

Sorry that's pretty vague, I think you'll have to figure that out for yourself

[shaharKeisarApps]

No problem, thank you very much, the main thing for me is to hear that there is no limit from the Circuit framework side.

For who also interested in that behavior, here is a very basic code sample.
Feel free to improve/ give some notes/ fix:)

First, define screens in the flow(kind of nav graph):

sealed class Screen {
    object HomeScreen : Screen()
    object PasswordScreen : Screen()
    object TransferMoneyScreen : Screen()
}

Next, create a Presenter for each screen:

class HomePresenter(private val navigator: Navigator) {
    fun goToPasswordScreen() {
        navigator.goTo(Screen.PasswordScreen)
    }
}

class PasswordPresenter(private val navigator: Navigator, private val destination: Screen) {
    fun checkPasswordAndNavigate(password: String) {
        if (password == "correctPassword") {
            navigator.goTo(destination)
        }
    }
}

class TransferMoneyPresenter(private val navigator: Navigator) {
    fun transferMoney(amount: Int) {
        // Transfer money logic here
    }
}

Finally:

setContent {
    val backstack = rememberSaveableBackStack { push(Screen.HomeScreen) }
    val navigator = rememberCircuitNavigator(backstack)

    NavigableCircuitContent(navigator, backstack) { screen ->
        when (screen) {
            is Screen.HomeScreen -> HomeScreen(HomePresenter(navigator))
            is Screen.PasswordScreen -> PasswordScreen(PasswordPresenter(navigator, Screen.TransferMoneyScreen))
            is Screen.TransferMoneyScreen -> TransferMoneyScreen(TransferMoneyPresenter(navigator))
        }
    }
}

[shaharKeisarApps]

@ZacSweers Could you provide some insights into the benefits or reasons for choosing this navigation approach (which might seems to be tightly-coupled please fix me if i'm wrong) over an event-based as in NowInAndroid app? Are there specific advantages in terms of scaleability, code maintainability, or user experience that influenced this decision?

Thanks!

[ZacSweers]

Sorry I'm not familiar with the event approach you're referring to in NIA, can you link an example?

[shaharKeisarApps]

Sure,
here is the code( also mentioned above):

/**
 * Top-level navigation graph. Navigation is organized as explained at
 * https://d.android.com/jetpack/compose/nav-adaptive
 *
 * The navigation graph defined in this file defines the different top level routes. Navigation
 * within each route is handled using state and Back Handlers.
 */
@Composable
fun NiaNavHost(
    appState: NiaAppState,
    onShowSnackbar: suspend (String, String?) -> Boolean,
    modifier: Modifier = Modifier,
    startDestination: String = forYouNavigationRoute,
) {
    val navController = appState.navController
    NavHost(
        navController = navController,
        startDestination = startDestination,
        modifier = modifier,
    ) {
        // TODO: handle topic clicks from each top level destination
        forYouScreen(onTopicClick = {})
        bookmarksScreen(
            onTopicClick = navController::navigateToTopic,
            onShowSnackbar = onShowSnackbar,
        )
        searchScreen(
            onBackClick = navController::popBackStack,
            onInterestsClick = { appState.navigateToTopLevelDestination(INTERESTS) },
            onTopicClick = navController::navigateToTopic,
        )
        interestsGraph(
            onTopicClick = { topicId ->
                navController.navigateToTopic(topicId)
            },
            nestedGraphs = {
                topicScreen(
                    onBackClick = navController::popBackStack,
                    onTopicClick = {},
                )
            },
        )
    }
}

Use of Callbacks for Navigation: Each screen (e.g., forYouScreen, bookmarksScreen, searchScreen, etc.) is provided with callbacks (like onTopicClick, onBackClick) as parameters. These callbacks are essentially functions that get called when a certain navigation event occurs. This design means that the screens themselves do not directly handle navigation logic; they simply invoke these callbacks when necessary.

Centralized Navigation Logic: The navigation logic is centralized in the NiaNavHost composable function. Here, the navController is used to define the navigation actions. This controller is part of the NiaAppState, which likely holds the application-wide state and navigation logic. By doing so, the specific logic for navigation is abstracted away from individual screens.

Decoupling of Screens: Because each screen is only aware of the callbacks and not the actual navigation logic or destinations, they are decoupled from the navigation structure of the app. This means that changes in navigation routes or logic can be made without directly modifying the individual screen composables. It enhances modularity and makes the screens more reusable and easier to test.

Flexibility in Navigation Flow: This approach allows for flexibility in changing the navigation flow of the application. Since the screens don't have hardcoded navigation destinations, altering the flow (like changing the destination of onTopicClick) can be done in NiaNavHost without impacting the individual screens.

Consistency in Handling Navigation: By centralizing navigation logic, you also ensure consistency in how navigation is handled across different parts of the app. This makes the app's navigation more predictable and easier to manage.

In summary, in your example, navigation is managed centrally through NiaNavHost using a NavController, and screens are provided with callback functions for navigation events. This design ensures that the screens are unaware of and decoupled from the specific details of the navigation logic, promoting a clean, modular, and maintainable codebase.

[ZacSweers]

The mechanics of NIA are different, but they largely achieve the same purpose. Instead of callbacks we just use concrete screen classes. Circuit is just one pattern, you can use whichever pattern you prefer or works best for your project. Each has their own pros and cons.

A nice thing about Circuit's flexibility is that you could probably replicate that api on top of circuit components if you're really set on hiding the navigator from presenters, and I suspect if you did you'd see why it's a thin abstraction.

[shaharKeisarApps]

I understand that Circuit adopts a pattern where each 'circuit' manages its own navigation. However, I'm curious about the rationale behind this design choice, particularly why navigation control is not abstracted to a layer above, similar to the approach in the NowInAndroid example. In such a setup, circuits would not need to be aware of their origin or navigation destinations, promoting a more decoupled architecture. Could you shed some light on the benefits or reasons for preferring navigation control within each circuit, as opposed to a higher-level abstraction?

[ZacSweers]

Circuit screens aren't aware of their origins nor are they tightly coupled. This more or less just boils down to circuit presenters having access to a navigator and being able to pass screens as destination keys to it. This is plenty of abstraction because they don't have direct access to the new circuit itself navigating to, and one screen can contextually go to different destinations.

Your NIA example above requires all routing to be centrally and statically defined. That works fine for simple cases but quickly breaks down for nontrivial/dynamic or nested cases.