0.19.0

What's Changed

Navigation with results

This release introduces support for inter-screen navigation results. This is useful for scenarios where you want to pass data back to the previous screen after a navigation event, such as when a user selects an item from a list and you want to pass the selected item back to the previous screen.

var photoUrl by remember { mutableStateOf<String?>(null) }
val takePhotoNavigator = rememberAnsweringNavigator<TakePhotoScreen.Result>(navigator) { result ->
  photoUrl = result.url
}

// Elsewhere
takePhotoNavigator.goTo(TakePhotoScreen)

// In TakePhotoScreen.kt
data object TakePhotoScreen : Screen {
  @Parcelize
  data class Result(val url: String) : PopResult
}

class TakePhotoPresenter {
  @Composable fun present(): State {
    // ...
    navigator.pop(result = TakePhotoScreen.Result(newFilters))
  }
}

See the new section in the navigation docs for more details, as well as updates to the Overlays docs that help explain when to use an Overlay vs navigating to a Screen with a result.

Support for multiple back stacks

This release introduces support for saving/restoring navigation state on root resets (aka multi back stack). This is useful for scenarios where you want to reset the back stack to a new root but still want to retain the previous back stack's state, such as an app UI that has a persistent bottom navigation bar with different back stacks for each tab.

This works by adding two new optional saveState and restoreState parameters to Navigator.resetRoot().

navigator.resetRoot(HomeNavTab1, saveState = true, restoreState = true)
// User navigates to a details screen
navigator.push(EntityDetails(id = foo))
// Later, user clicks on a bottom navigation item
navigator.resetRoot(HomeNavTab2, saveState = true, restoreState = true)
// Later, user switches back to the first navigation item
navigator.resetRoot(HomeNavTab1, saveState = true, restoreState = true)
// The existing back stack is restored, and EntityDetails(id = foo) will be top of
// the back stack

There are times when saving and restoring the back stack may not be appropriate, so use this feature only when it makes sense. A common example where it probably does not make sense is launching screens which define a UX flow which has a defined completion, such as onboarding.

New Tutorial!

On top of Circuit's existing docs, we've added a new tutorial to help you get started with Circuit. It's a step-by-step guide that walks you through building a simple inbox app using Circuit, intended to serve as a sort of small code lab that one could do in 1-2 hours. Check it out here.

Overlay Improvements

• New: Promote AlertDialogOverlay, BasicAlertDialogOverlay, and BasicDialogOverlay to circuitx-overlay.
• New: Add OverlayEffect to circuit-overlay. This offers a simple composable effect to show an overlay and await a result.

  OverlayEffect(state) { host ->
    val result = host.show(AlertDialogOverlay(...))
    // Do something with the result
  }

• Add OverlayState and LocalOverlayState to circuit-overlay. This allows you to check the current overlay state (UNAVAILABLE, HIDDEN, or SHOWING).
• Mark OverlayHost as @ReadOnlyOverlayApi to indicate that it's not intended for direct implementation by consumers.
• Mark Overlay as @Stable.

Misc

• Make NavEvent.screen public.
• Change Navigator.popUntil to be exclusive.
• Add Navigator.peek() to peek the top screen of the back stack.
• Add Navigator.peekBackStack() to peek the top screen of the back stack.
• Align spelling of back stack parameters across all APIs to backStack.
• Refreshed iOS Counter sample using SPM and SKIE.
• Convert STAR sample to KMP. Starting with Android and Desktop.
• Fix baseline profiles packaging. Due to a bug in the baseline profile plugin, we were not packaging the baseline profiles in the artifacts. This is now fixed.
• Mark BackStack.Record as @Stable.
• Fix an infinite loop in the onRootPop of the Android rememberCircuitNavigator.
• Update the default decoration to better match the android 34 transitions.
• Update androidx.lifecycle to 2.7.0.
• Update to compose multiplatform to 1.5.12.
• Update to compose to 1.6.1.
• Update to compose-bom to 2024.02.00.
• Update compose-compiler to 1.5.9.
• Update AtomicFu to 0.23.2.
• Update Anvil to 2.4.9.
• Update KotlinPoet to 1.16.0.
• Compile against KSP 1.9.22-1.0.17.

Special thanks to @milis92, @ChrisBanes, and @vulpeszerda for contributing to this release!

New Contributors

• @milis92 made their first contribution in #1116
• @vulpeszerda made their first contribution in #1160

Full Changelog: 0.18.2...0.19.0