Generic mechanism for navigation

[aartikov]

Hi, Arkadii.

First of all, thank you for the great library. It saved hundreds of hours for us.
I like that Decompose components are independent from UI. I don't know another libraries with this feature.

Recently I found out a library called appyx - https://bumble-tech.github.io/appyx/
It is tied to Jetpack Compose, so it is not suitable for KMM apps. But there is one killer feature. Appyx has a concept called navigation model. Any type of navigation is based on it. There are build in navigation models. And it is easy to create a custom one. Take a look, please - https://bumble-tech.github.io/appyx/navigation/model-driven-navigation/
I also had watched a video about it https://www.droidcon.com/2022/09/29/model-driven-navigation-with-jetpack-compose-from-zero-to-hero/ and I am very impressed.

So, i'm wondering do you plan to make some generic mechanism for navigation in Decompose? Decompose has a child stack and a child overlay, but it is non-trivial to create something custom such as a view pager and other examples from Appyx.

[arkivanov]

Thanks for raising the idea! I already looked at Appyx. Decompose is designed differently in many ways. As you mentioned, Decompose is multiplatform and doesn't depend on Compose. So the navigation state has to be fully exposed to the UI. This makes it possible to plug any UI externally. But on the other hand, things like transitions and UI state restoration also have to be handled externally, Decompose Core can't do it for you. So the outcome here is that there must be a complete navigation state exposed from components - e.g. Value<ChildStack>, where ChildStack contains the whole stack with components and configurations.

(Not only) because of that, Decompose goes in another direction. It is based around the concept of ComponentContext, and different navigation models are provided via extension functions like ComponentContext.childStack or ComponentContext.childOverlay. Eventually I'm happy to add more models when needed. And the main idea is that custom navigation modules can be built on top of the predefined ones. E.g. Child Overlay is based on top of Child Stack.

[aartikov]

Thank you for clarifing the difference between Decompose and Appyx.

So, ComponentContext has everything to implement different navigation models as extension functions. We can do it from scratch (I didn't try it myself, but I suppose it will be tricky). Or we can build it on top of childStack (this way is more newbie-friendly).

The idea of this thread is to introduce a very generic predifined model, so more use cases can be done in a simpler way. Lets, call it childCollection. It would handle arbitrary count of children. The children can be in any states (active, inactive or destroyed) independently of each other. And there should be some way to modify it.

childStack and childOverlay would be build on top of childCollection. Then we can build more models, for example:

• childList - creates multiple childs, every child is active when a parent is active. Use case: a bunch of cards on a screen, each card has its own component.
• childSwitcher (probably bad naming) - creates multiple childs, only one child can be active. Use case: view pager.
• and so on

[arkivanov]

Thanks for the clarification! Yes, ComponentContext provides everything for writing custom navigation models from scratch. This gives full flexibility. Currently, the long term strategy is to provide a number of predefined navigation models as extension functions on ComponentContext. We already have Child Stack and Child Overlay, plus I'm thinking about something like Child Pager and Child List. Custom navigation models could be built either on top of predefined ones (like Child Overlay is built on top of Child Stack), or from scratch.

But I also completely understand your point! I will think about it and maybe prototype something, and provide updates here.

[aartikov]

Awesome 👍

[arkivanov]

I've been playing with various APIs and for now I have the following in mind. It seems working for Child Stack and Child Overlay, and also flexible enough for custom implementations. What do you think?

The idea is to have NavState and ChildNavState interfaces, that provide a list of child configurations and corresponding child statuses. The ChildNavState.Status enum represents the status of a child, where: DESTROYED means that the child is in destroyed state, INACTIVE means that the child is in created (or stopped) state, and ACTIVE means the child is resumed. The NavState is persistent, which makes it possible to preserve the entire navigation state.

The navigation is performed by transforming old NavState to a new one. The implementation is able to diff old and new NavState, and switch children as needed. It is also possible to save and restore child states via StateKeeper, retain instances via InstanceKeeper, and handle back button presses via BackHandler.

I also created a draft implementation. The existing integration tests for Child Stack and Child Overlay are passing, so at first glance everything seems working. However, after unit testing there are might be unexpected blockers, issues or changes.

interface NavigationSource<out T : Any> {
    fun subscribe(observer: (T) -> Unit)
    fun unsubscribe(observer: (T) -> Unit)
}

interface NavState<out C : Any> {
    val children: List<ChildNavState<C>>
}

interface ChildNavState<out C : Any> {
    val configuration: C
    val status: Status

    enum class Status {
        DESTROYED,
        INACTIVE,
        ACTIVE,
    }
}

// C - type of configuration
// T - type of child components
// E - type of navigation event
// N - type of custom nav state, implements NavState
// S - type of custom resulting state
// All functions are supposed to be stateless and without side effects 
fun <C : Any, T : Any, E : Any, N : NavState<C>, S : Any> ComponentContext.children(
    source: NavigationSource<E>,
    key: String,
    initialNavState: () -> N, // Returns initial NavState, called when there is no saved state
    saveNavState: (navState: N) -> ParcelableContainer, // Saves the NavState into ParcelableContainer
    restoreNavState: (container: ParcelableContainer) -> N, // Restores the NavState from ParcelableContainer
    navTransformer: (navState: N, event: E) -> N, // Transforms old NavState to a new one by the provided navigation event
    onEventComplete: (event: E, newNavState: N, oldNavState: N) -> Unit, // Called after the navigation event is handled
    backTransformer: (navState: N) -> (() -> N)?, // Called after each navigation event, returns a transformer from old NavState to a new one on back press, or null not allowed
    stateMapper: (navState: N, children: List<Child<C, T>>) -> S, // Returns a new state based on new NavState
    childFactory: (configuration: C, componentContext: ComponentContext) -> T,
): Value<S>

[arkivanov]

Thanks for the feedback! Yeah, perhaps worth renaming for consistency.

1. NavState and ChildNavState are interfaces to allow clients to add their own data. E.g. in a pager-like navigation there could be additional index property stored in NavState.
2. The mapping to S is there to allow arbitrary state type, so NavState + List<Child> = CustomState

[aartikov]

Wow! You have released it already. Thank you very much!

[arkivanov]

Yes! Also existing Child Stack and Child Overlay are now using the new Generic Navigation. Hopefully nothing is broken 🫣

[arkivanov]

The sample app is updated! Check out the docs - https://arkivanov.github.io/Decompose/navigation/children/overview/#sample-project

[aartikov]

Looks cool. Thank you!