Multiplatform codegen library for typed navigation in Navigation 3.

The library is designed to keep the same level of control that Navigation 3 gives to developers. It solves the problem of writing a lot of boring and repetitive code that will link your Composable Views, typed navigation data classes, and entries to combine all of the above into NavDisplay.

It introduces several concepts:

• Branch - it's basically a NavKey, a Composable component representation with all its arguments. These are used to build the BackStack for Typed navigation.
• Tree - A collection of related Branches and other Trees that it includes. In collaboration with NavDisplay, it provides access to all associated Branches and subTrees via the BackStack.

By the way, this library can be used without KSP if you really like writing boilerplate by hand.

Somewhat inspired by the awesome Android library compose-destinations

Firstly, you need to install the latest version of KSP plugin in your project.

plugins {
    // ...
    // check for the latest version here https://github.com/google/ksp/releases
    id("com.google.devtools.ksp") version "2.3.3" 
}

In build.gradle.kts at the kotlin block of your project, add dependencies to commonMain

kotlin {
    // ...
    sourceSets {
        // ...
        commonMain {
            kotlin.srcDir("build/generated/ksp/metadata/commonMain/kotlin")
            dependencies {
                // ...
                implementation("io.github.fopwoc:nav3ksp:1.0.1")
                implementation("io.github.fopwoc:nav3ksp-annotation:1.0.1")
            }
        }
    }    
}

Add KSP plugin dependency to the dependencies block.

dependencies {
    // ...
    add("kspCommonMainMetadata", "io.github.fopwoc:nav3ksp-processor:1.0.1")
}

And finally, add somewhere in your build.gradle.kts this block to run codegen on every build. Or not, then you have to call this job by hand.

tasks.named("preBuild") {
    dependsOn("kspCommonMainKotlinMetadata")
}

I already said that, actually, you can use the library without any code generation, just as boilerplate "framework". In this case, you don't need to install KSP plugin, all you have to do is add only this dependency to your build.gradle.kts project and have fun implementing abstract classes of all kinds.

sourceSets {
    commonMain.dependencies {
        // ...
        implementation("io.github.fopwoc:nav3ksp:1.0.1")
    }
}

To begin, we need to declare an annotation that will represent our Tree

@Tree
annotation class RootTree

Then, for each View that will be part of this Tree, we must specify the Branch annotation and indicate the connection to the Tree

@Branch(RootTree::class)
@Composable
fun ExampleView() { 
    // ...
}

Finally, call NavDisplay, provide it with the generated NavTreeLayout and NavTreeBuilder of your Tree, and manually specify the first screen in BackStack. Or not just one, it's vararg.

val LocalBackStack = compositionLocalOf<NavBackStack<NavKey>> {
    error("No LocalBackStack provided")
}

@Composable
fun App() {
    CompositionLocalProvider(
        LocalBackStack provides RootNavTreeLayout.rememberTreeBackStack(RootNavTree.Example)
    ) {
        NavDisplay(
            navTreeBuilder = RootNavTreeBuilder,
            backStackLocalComposition = LocalBackStack
        )
    } 
}

That's it!

For more examples, you can see the 'example' module with a multiplatform app that shows a few usages of this library.

1. Simple navigation - Simple navigation.
2. Back Handled - Like simple navigation, but the back gesture is handled in the view.
3. ViewModel - Example of how this lib handles view models.
4. Arguments - Navigation with typed arguments.
5. Nested - Nested navigation with bottom bar and 3 views. Also, an example of handing backstack from another scope.
6. Result - Navigation to form with result handling by another View.
7. Manual - Non-KSP usage, a-ka 'Boilerplate by hand'.
8. Dialog - Dialog popup example via Scene and route metadata