Merge branch 'main' into dt/koin_nav3

# Conflicts:
#	app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt
#	gradle/libs.versions.toml

Author: arnaudgiuliani

README.md

@@ -1,6 +1,11 @@
 # Navigation 3 - Code recipes
 [Jetpack Navigation 3](https://goo.gle/nav3) is a library for app navigation. This repository contains recipes for how to 
-use its APIs to implement common navigation use cases.
+use its APIs to implement common navigation use cases. Each recipe introduces a single concept. Instead
+of making existing recipes more complex, there should be a new recipe for that particular concept.
+
+Every Navigation 3 release will be an opportunity for patterns you see in recipes to "graduate" and become
+(optional) helpers in the library itself. Then we'll update the recipe to use that prebuilt helper, thus
+ensuring that the recipes continue to be a good way to approach these kinds of problems.
 
 ## Recipes
 These are the recipes and what they demonstrate. 
@@ -10,19 +15,23 @@ These are the recipes and what they demonstrate.
 - **[Saveable back stack](app/src/main/java/com/example/nav3recipes/basicsaveable)**: As above, with a persistent back stack.
 - **[Entry provider DSL](app/src/main/java/com/example/nav3recipes/basicdsl)**: As above, using the entryProvider DSL.
 
-### Layouts and animations
-- **[Dialog](app/src/main/java/com/example/nav3recipes/dialog)**: Shows how to create a Dialog destination.
+### Layouts using Scenes
+- **[List-Detail Scene](app/src/main/java/com/example/nav3recipes/scenes/listdetail)**: Shows how to create a custom, list-detail layout using a `Scene` and `SceneStrategy` (see video of UI behavior below).
+- **[Two pane Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane)**: Shows how to create a custom, 2-pane layout.
 - **[BottomSheet](app/src/main/java/com/example/nav3recipes/bottomsheet)**: Shows how to create a BottomSheet destination.
-- **[Custom Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane)**: Shows how to create a custom layout using a `Scene` and `SceneStrategy` (see video of UI behavior below).
-- **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination.
+- **[Dialog](app/src/main/java/com/example/nav3recipes/dialog)**: Shows how to create a Dialog.
 
 ### Material adaptive layouts
 Examples showing how to use the layouts provided by the [Compose Material3 Adaptive Navigation3 library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2)
 - **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material adaptive list-detail layout.
 - **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material adaptive supporting pane layout.
 
+### Animations
+- **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Shows how to override the default animations for all destinations and a single destination.
+
 ### Common use cases
-- **[Common navigation UI](app/src/main/java/com/example/nav3recipes/commonui)**: A common navigation toolbar where each item in the toolbar navigates to a top level destination.
+- **[Common navigation UI](app/src/main/java/com/example/nav3recipes/commonui)**: A common navigation toolbar where each item in the toolbar navigates to a top level destination.  
+- **[Multiple back stacks](app/src/main/java/com/example/nav3recipes/multiplestacks)**: Shows how to create multiple top level routes, each with its own back stack. Top level routes are displayed in a navigation bar allowing users to switch between them. State is retained for each top level route, and the navigation state persists config changes and process death.  
 - **[Conditional navigation](app/src/main/java/com/example/nav3recipes/conditional)**: Switch to a different navigation flow when a condition is met. For example, for authentication or first-time user onboarding.
 
 ### Architecture
@@ -43,9 +52,9 @@ Examples showing how to use the layouts provided by the [Compose Material3 Adapt
 - **Android XR**: Custom navigation and layout behavior for Android XR
 
 ## Custom layout example
-The following is a screen recording showing the navigation behavior of a [custom, two-pane Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane).
+The following is a screen recording showing the navigation behavior of a [custom, list-detail Scene](app/src/main/java/com/example/nav3recipes/scenes/listdetail).
 
-![Custom layout example](/docs/images/TwoPaneScene.gif)
+![Custom layout example](/docs/images/ListDetailScene.gif)
 
 ## Instructions
 Clone this repository and open the root folder in [Android Studio](https://developer.android.com/studio). Each recipe is contained in its own package with its own `Activity`.
@@ -56,6 +65,9 @@ If the issue is _directly related to this project_, as in, it's reproducible wit
 ## Contributing
 We'd love to accept your contributions. Please follow [these instructions](CONTRIBUTING.md).
 
+## Compose Multiplatform Recipes
+CMP recipes can be found [here](https://github.com/terrakok/nav3-recipes).
+
 ## License
 ```
 Copyright 2025 The Android Open Source Project

app/build.gradle.kts

@@ -18,7 +18,7 @@ plugins {
     alias(libs.plugins.android.application)
     alias(libs.plugins.kotlin.android)
     alias(libs.plugins.kotlin.compose)
-    alias(libs.plugins.jetbrains.kotlin.serialization)
+    alias(libs.plugins.kotlin.serialization)
     alias(libs.plugins.hilt)
     alias(libs.plugins.ksp)
 }

app/src/main/AndroidManifest.xml

@@ -77,10 +77,6 @@
             android:name=".material.supportingpane.MaterialSupportingPaneActivity"
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes"/>
-        <activity
-            android:name=".scenes.twopane.TwoPaneActivity"
-            android:exported="true"
-            android:theme="@style/Theme.Nav3Recipes"/>
         <activity
             android:name=".animations.AnimatedActivity"
             android:exported="true"
@@ -150,6 +146,18 @@
             android:name=".migration.step7.Step7MigrationActivity"
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes"/>
+        <activity
+            android:name=".scenes.twopane.TwoPaneActivity"
+            android:exported="true"
+            android:theme="@style/Theme.Nav3Recipes"/>
+        <activity
+            android:name=".scenes.listdetail.ListDetailActivity"
+            android:exported="true"
+            android:theme="@style/Theme.Nav3Recipes"/>
+        <activity
+            android:name=".multiplestacks.MultipleStacksActivity"
+            android:exported="true"
+            android:theme="@style/Theme.Nav3Recipes"/>
     </application>
 
 </manifest>

app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.example.nav3recipes
 
 import android.app.Activity
@@ -33,15 +49,17 @@ import com.example.nav3recipes.bottomsheet.BottomSheetActivity
 import com.example.nav3recipes.commonui.CommonUiActivity
 import com.example.nav3recipes.conditional.ConditionalActivity
 import com.example.nav3recipes.dialog.DialogActivity
+import com.example.nav3recipes.material.listdetail.MaterialListDetailActivity
+import com.example.nav3recipes.material.supportingpane.MaterialSupportingPaneActivity
+import com.example.nav3recipes.multiplestacks.MultipleStacksActivity
 import com.example.nav3recipes.modular.hilt.HiltModularActivity
 import com.example.nav3recipes.modular.koin.KoinModularActivity
 import com.example.nav3recipes.passingarguments.viewmodels.basic.BasicViewModelsActivity
 import com.example.nav3recipes.passingarguments.viewmodels.hilt.HiltViewModelsActivity
 import com.example.nav3recipes.passingarguments.viewmodels.koin.KoinViewModelsActivity
-import com.example.nav3recipes.material.listdetail.MaterialListDetailActivity
-import com.example.nav3recipes.material.supportingpane.MaterialSupportingPaneActivity
 import com.example.nav3recipes.results.event.ResultEventActivity
 import com.example.nav3recipes.results.state.ResultStateActivity
+import com.example.nav3recipes.scenes.listdetail.ListDetailActivity
 import com.example.nav3recipes.scenes.twopane.TwoPaneActivity
 import com.example.nav3recipes.ui.setEdgeToEdgeConfig
 
@@ -61,17 +79,22 @@ private val recipes = listOf(
     Recipe("Basic DSL", BasicDslActivity::class.java),
     Recipe("Basic Saveable", BasicSaveableActivity::class.java),
 
-    Heading("Layouts and animations"),
+    Heading("Layouts using Scenes"),
+    Recipe("List-detail", ListDetailActivity::class.java),
+    Recipe("Two pane", TwoPaneActivity::class.java),
     Recipe("Bottom Sheet", BottomSheetActivity::class.java),
-    Recipe("Material list-detail layout", MaterialListDetailActivity::class.java),
-    Recipe("Material supporting-pane layout", MaterialSupportingPaneActivity::class.java),
     Recipe("Dialog", DialogActivity::class.java),
+
+    Heading("Material adaptive layouts"),
     Recipe("Material list-detail layout", MaterialListDetailActivity::class.java),
-    Recipe("Two pane layout (custom scene)", TwoPaneActivity::class.java),
-    Recipe("Animations", AnimatedActivity::class.java),
+    Recipe("Material supporting-pane layout", MaterialSupportingPaneActivity::class.java),
+
+    Heading("Animations"),
+    Recipe("NavDisplay and NavEntry animations", AnimatedActivity::class.java),
 
     Heading("Common use cases"),
     Recipe("Common UI", CommonUiActivity::class.java),
+    Recipe("Multiple Stacks", MultipleStacksActivity::class.java),
     Recipe("Conditional navigation", ConditionalActivity::class.java),
 
     Heading("Architecture"),

app/src/main/java/com/example/nav3recipes/animations/AnimatedActivity.kt

@@ -25,11 +25,6 @@ import com.example.nav3recipes.ui.setEdgeToEdgeConfig
 import kotlinx.serialization.Serializable
 
 
-/**
- * This recipe shows how to override the default animations at the `NavDisplay` level, and at the
- * individual destination level, shown for `ScreenC`.
- *
- */
 @Serializable
 private data object ScreenA : NavKey
 

app/src/main/java/com/example/nav3recipes/animations/README.md

@@ -0,0 +1,11 @@
+# Animations Recipe
+
+This recipe shows how to override the default animations at the `NavDisplay` level, and at the individual destination level.
+
+## How it works
+
+The `NavDisplay` composable takes `transitionSpec`, `popTransitionSpec`, and `predictivePopTransitionSpec` parameters to define the animations for forward, backward, and predictive back navigation respectively. These animations will be applied to all destinations by default.
+
+In this example, we use `slideInHorizontally` and `slideOutHorizontally` to create a sliding animation for forward and backward navigation.
+
+It is also possible to override these animations for a specific destination by providing a different `transitionSpec` and `popTransitionSpec` to the `entry` composable. In this recipe, `ScreenC` has a custom vertical slide animation.

app/src/main/java/com/example/nav3recipes/basic/BasicActivity.kt

@@ -29,10 +29,6 @@ import com.example.nav3recipes.content.ContentBlue
 import com.example.nav3recipes.content.ContentGreen
 import com.example.nav3recipes.ui.setEdgeToEdgeConfig
 
-/**
- * Basic example with two screens, showing how to use the Navigation 3 API.
- */
-
 private data object RouteA
 
 private data class RouteB(val id: String)

app/src/main/java/com/example/nav3recipes/basic/README.md

@@ -0,0 +1,13 @@
+# Basic Recipe
+
+This recipe shows a basic example of how to use the Navigation 3 API with two screens.
+
+## How it works
+
+This example defines two routes: `RouteA` and `RouteB`. `RouteA` is a `data object` representing a simple screen, while `RouteB` is a `data class` that takes an `id` as a parameter.
+
+A `mutableStateListOf<Any>` is used to manage the navigation back stack.
+
+The `NavDisplay` composable is used to display the current screen. Its `entryProvider` parameter is a lambda that takes a route from the back stack and returns a `NavEntry`. Inside the `entryProvider`, a `when` statement is used to determine which composable to display based on the route.
+
+To navigate from `RouteA` to `RouteB`, we simply add a `RouteB` instance to the back stack. The `id` is passed as an argument to the `RouteB` data class.

app/src/main/java/com/example/nav3recipes/basicdsl/BasicDslActivity.kt

@@ -30,10 +30,6 @@ import com.example.nav3recipes.content.ContentGreen
 import com.example.nav3recipes.ui.setEdgeToEdgeConfig
 import kotlinx.serialization.Serializable
 
-/**
- * Basic example with two screens that uses the entryProvider DSL and has a persistent back stack.
- */
-
 @Serializable
 private data object RouteA : NavKey
 

app/src/main/java/com/example/nav3recipes/basicdsl/README.md

@@ -0,0 +1,13 @@
+# Basic DSL Recipe
+
+This recipe shows a basic example of how to use the Navigation 3 API with two screens, using the `entryProvider` DSL and a persistent back stack.
+
+## How it works
+
+This example is similar to the basic recipe, but with a few key differences:
+
+1.  **Persistent Back Stack**: It uses `rememberNavBackStack(RouteA)` to create and remember the back stack. This makes the back stack persistent across configuration changes (e.g., screen rotation). To use `rememberNavBackStack`, the navigation keys must be serializable, which is why `RouteA` and `RouteB` are annotated with `@Serializable` and implement the `NavKey` interface.
+
+2.  **`entryProvider` DSL**: Instead of a `when` statement, this example uses the `entryProvider` DSL to define the content for each route. The `entry<RouteType>` function is used to associate a route type with its composable content.
+
+The navigation logic remains the same: to navigate from `RouteA` to `RouteB`, we add a `RouteB` instance to the back stack.