• Compose 1.3.0

Added

Configuring SafeRoute

If you want to customize and/or adjust the way SafeRoute works you can do so by passing arguments to the processor.

Default Package name

Some files, such as MainGraph, generated by SafeRoute are generated without specific relation to the package name. Their package name is based on the first element the processor encounters, which is not always ideal and can lead to unintended behaviour To fix this, you can specify the defaultPackageName where files like these will be placed

kapt {
    arguments {
        arg("safeRoute.defaultPackageName", "cz.levinzonr.saferoute.navigation")
    }
}

ksp {
    arg("safeRoute.defaultPackageName", "cz.levinzonr.saferoute.navigation")
}

Bugfixes

• Fixed a bug when obtaining null values from SavedStateHandle

KSP Support

From version 2.5.0 Safe Route now has the support for Kotlin Symbol Processing (KSP). The API is the same so the migration should be more or less painless (considering you already using 2.5.0-X version), however, the imports might change. Here is how to get started.

This is a pre-release based on the 2.5.0-beta01, make sure to also check whats new in beta01 release here

⚠️ If you dont want to use KSP you can still use KAPT, KAPT support is not going anywhere :). However in order to keep the modules name aligned, compiler artifact was renamed into processor-kapt

    kapt("com.github.levinzonr.compose-safe-routing:processor-kapt:2.5.0-beta02")

Add KSP Plugin (if you haven't already)

Gradle

plugins {
    id  "com.google.devtools.ksp" version '"1.6.10-1.0.3" // 
}

Kotlin

plugins {
    id("com.google.devtools.ksp") version "1.6.10-1.0.3" // Depends on your kotlin version
}

Add KSP Build Directory to your source sets (if you havent already)

Gradle

applicationVariants.all { variant ->
    kotlin.sourceSets {
        getByName(variant.name) {
            kotlin.srcDir("build/generated/ksp/${variant.name}/kotlin")
        }
    }
}

Kotlin

applicationVariants.all {
    kotlin.sourceSets {
        getByName(name) {
            kotlin.srcDir("build/generated/ksp/$name/kotlin")
        }
    }
}

Add Safe Route KSP Processor

The final step would be to add a new dependency (if you've been using kapt processor you can now remove it) and build the project and fix some imports

    ksp("com.github.levinzonr.compose-safe-routing:processor-ksp:2.5.0-beta02")

Disclaimer ⚠️

This update is quite big in terms of introducing new logic and deprecating the logic that was here since the beginning. Thus, I'd like to gather as much feedback as possible and encourage you to open issues in case you have any suggestions regarding newly introduced stuff. I'm also making this update as beta as there are things I would like to make it in full 2.5.0 and so there is somewhat of a breathing room in case of any feedback :) Thanls!

NavGraph Support

Version 2.5.0 introduces support to the Navigation Graphs so you can structure your routes in a more concise way. By default, all your current routes will be a part of the "Main" Graph - the default graph all route annotations have, and, since all NavGraphs need to have a starting point, you need to declare of your routes to be a "start", otherwise the build may fail

@Route(
    transition = AnimatedRouteTransition.Default::class,
    navGraph = RouteNavGraph(start = true)
)

Defining Custom Graphs

If you want to define your graph you can simply set another graph name and set a starting route for it

@Route(
    name = "PokemonList",
    transition = FadeInFadeOutTransition::class,
    navGraph = RouteNavGraph("pokedex", start = true)
)

This will generate a new file and called PokedexGraph and PokedexGraphRoutes which you can you for navigation or declaration, like so

navigation(PokedexGraph) {
    pokemonList {
        // Composable content()
    }
}
and navigation
navController.navigateTo(PokedexGraph)
navContoller.navigateTo(PokemonDetailsRoute())

New Navigation APIs and Deprecation of the Old Ones

RoutesActions.kt were deprecated in favor of the invoke operator that is a part of RouteSpec. We've added another navController extension navigateTo() that can be used together with it. This results in one less generated file and more straightforward usage. NavController+Routes.kt will also be deleted in the future releases

2.4.X - Old behaviour

navController.navigate(RouteActions.toDetails("id")
navController.navigateToDetails("id")

2.5.0 - New behavior

navController.navigateTo(DetailsRoute("Id"))

Router API

2.5.0 Introduces new component called Router, which is basically a wrapper around your usual navController, but is specifically built to handle navigation using the newly introduced extensions. It is also an Interface, which means it would be easier to test your composables. Router can be accessed from Composition Local and used as so:

val router = LocalRouter.current
router.navigate(DetailsRoute("id"))

Deprecation of Routes.kt

Routes.kt is now also deprecated since we've introduced the navigation graphs which allow you to structure in a similar fashion but in a more logical and flexible way. By Default, all your Routes will be a part of the MainGraphRoutes.kt so the migration should be fairly simple. Every new graph will hold its own set of Routes.

2.4.0 Release Notes

Introducing RouteTransitions

You can specify the desired transition using route builder.

route(Routes.Details, DefaultRouteTransition) { /* content */ }

You can also specify the desired transition right inside the @Route annotation like so. Doing so will allow you to use the generated route builder in your NavHost

@Route(
		name = "HomeScreen"
    transition = AnimatedRouteTransition.Default::class
)

// then you can use the generated route builder
NavHost {
   homeScreen {
     val viewModel = hiltViewModel()
      HomeScreen(viewModel)
   }
}

Misc

• name property of @Route annotation is now optional. By default it will take the name of the composable
• Navigation Compose version upated to 2.4.1

Fixes

• Skip generating multiple route actions for routes with optional arguments (#19)

Full Changelog: https://github.com/levinzonr/compose-safe-routing/compare/2.3.1...2.3.2

Fixes

• #14 - Add :at:null default value for the optional and nullable params, which can be later extracted as proper nulls instead of the "null" string text
• Fixes an issue with providing default String values

New RouteArgs API

RouteArgs are now more easily accesseble using CompositionLocal APIs. Using that approach there is no need to pass you arguments down the tree as they will be accessible for you entire Route. Plus, its way more convinient than deailing it NavBackStackEntry directly.

// OLD 2.2.X
composable(Routes.Details) { entry -> 
  val args = RouteDetailsArgsFactory.fromBackStackEntry(entry)
  DetailsScreen(args = args)
}

// NEW 2.3.0
composable(Routes.Details) {
  val args = LocalDetailsRouteArgs.current
  DetailsScreen(args = args)
}

// Or, retrieve it elsewhere :)
composable(Routes.Details) { DetailsScreen() }

DetailsScreen() {
  val args = LocalDetailsRouteArgs.current
  
  // also available through RouteSpec extension
  val args = Routes.Details.currentArgs
}

DeepLinks Support

SafeRoute now can handle the DeepLinks for you. Simply provide the deep link param for the desired Route and thats it. Any parameters you expecting being passed through the deeplink will be handled by the RouteArgs API as well, if they have the same names

@Composable
@Route(
    name = "details",
    args = [ RouteArg("id", String::class, isOptional =false)],
    deepLinks = [RouteDeeplink("app://deeplink/{id}")]
)
fun DetailsScreen() {
  // deeplink args will aslo be here
  val args = LocalDetatailsRouteArgs.current
  
}

Dialogs support

You can add use SafeRoute with dialogs.

fun NavGraphBuilder.mainGraph() {
  dialog(Routes.Popup) { Popup() }
  composable() { HomeScreen() }
}

API changes

*withArgs extensions

composableWithArgs and other *withArgs extensions have been deprecated in favor of CompositionLocalRouteArgs APIs

New Annotations

New Annotations with the same name were created inside the :core module to facilitate future development and introduce new features. Old annotations are now deprecated and will still work, however, some new features might be missing

Migration steps

1. Replace occurrences of cz.levinzonr.saferoute.annotations.RouteArg with cz.levinzonr.saferoute.core.annotations.RouteArg

2. Replace occurrences of cz.levinzonr.saferoute.annotations.Route with cz.levinzonr.saferoute.core.annotations.Route

3. Argument types are now specified using KClass<*>, list of supported types has not changed

NavController Extensions

RouteActions are now available through the extensions of the navController.

// 2.1.X
navController.navigate(RouteActions.toDetails("myId"))

// 2.2.0
navController.navigateToDetails("myId")

Dependencies Updates

• Update Navigation Compose to 2.4.0-alpha10
• Update Accompanist to 0.20.0

• Accompanist Support https://github.com/levinzonr/compose-safe-routing/blob/master/RELEASE_NOTES.md/#210-release-notes

2.0.0 Release Notes

NavGraphBuilder Extensions

The library now provides multiple extension function that you can use to declare your Routes

1.0.X

composable(Routes.screen.path, RouteSpec.screen.navArgs) { entry ->
   val args = ScreenArgs.fromBackStackEntry(it)
}

2.0.0

composable(Routes.Screen) {
   val args = ScreenArgsFactory.fromBackStackEntry(it)
}

// or, in case you dont want to handle arguments manually
composableWithArgs(Routes.Screen) { _, args
   // you screen             
}

Minor changes

• Custom NavHost() that can accept the RouteSpec
• navigation() builder

Breaking Changes

Imports

Annotations were moved to the different package. This can be fixed quicky by using find and replace from cz.levinzonr.router.core to cz.levinzonr.saferoute.annotations

1.0.X

import cz.levinzonr.router.core.Route
import cz.levinzonr.router.core.RouteArg
import cz.levinzonr.router.core.RouteArgType

2.0.0

import cz.levinzonr.saferoute.annotations.Route
import cz.levinzonr.saferoute.annotations.RouteArg
import cz.levinzonr.saferoute.annotations.RouteArgType

Retrieveing Arguments

Static functions of Args were replaced with arguments were replaced with ArgsFactories. fromBackStackEntry() is now an extension function

1.0.X

SomeRouteArgs.fromSavedStatedHandle(savedStateHandle)
SomeRouteArgs.fromBackStackEntry(entry)

2.0.0

SomeRouteArgsFactory.fromSavedStateHandle(savedStateHandle)
SomeRouteArgsFactory.fromBundle(bundle)
SomeRouteArgsFactory.fromBackStackEntry(entry) -- an extension, using fromBundle() under the hood

Generated Files

• RouteSpec.path renamed to RouteSpec.route

• RouteSpec.route now is always capitalised