Merge pull request #126 from android/dt/add-readmes

Add READMEs for each recipe.

Author: dturner

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.

app/src/main/java/com/example/nav3recipes/basicsaveable/BasicSaveableActivity.kt

@@ -30,13 +30,6 @@ import com.example.nav3recipes.content.ContentGreen
 import com.example.nav3recipes.ui.setEdgeToEdgeConfig
 import kotlinx.serialization.Serializable
 
-/**
- * Basic example with a persistent back stack state.
- *
- * The back stack persists config changes because it's created using `rememberNavBackStack`. This
- * requires that the back stack keys be both serializable and implement `NavKey`.
- */
-
 @Serializable
 private data object RouteA : NavKey
 

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

@@ -0,0 +1,11 @@
+# Basic Saveable Recipe
+
+This recipe shows a basic example of how to create a persistent back stack that survives configuration changes.
+
+## How it works
+
+To make the back stack persistent, we use the `rememberNavBackStack` function. This function creates and remembers the back stack across configuration changes (e.g., screen rotation).
+
+A requirement for using `rememberNavBackStack` is that the navigation keys (routes) must be serializable. In this example, `RouteA` and `RouteB` are annotated with `@Serializable` and implement the `NavKey` interface.
+
+This example uses a `when` statement within the `entryProvider` to map routes to their corresponding composables, but it could also be used with the `entryProvider` DSL.

app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt

@@ -36,16 +36,6 @@ import com.example.nav3recipes.content.ContentGreen
 import com.example.nav3recipes.ui.setEdgeToEdgeConfig
 import kotlinx.serialization.Serializable
 
-/**
- * This recipe demonstrates how to create a bottom sheet. It does this by:
- *
- * - Adding the `BottomSheetSceneStrategy` to the list of strategies used by `NavDisplay`.
- * - Adding `BottomSheetSceneStrategy.bottomSheet()` to a `NavEntry`'s metadata to indicate that it
- * is a bottom sheet. In this case it is applied to the `NavEntry` for `RouteB`.
- *
- * See also https://developer.android.com/guide/navigation/navigation-3/custom-layouts
- */
-
 @Serializable
 private data object RouteA : NavKey
 

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

@@ -0,0 +1,17 @@
+# Bottom Sheet Recipe
+
+This recipe demonstrates how to display a destination as a modal bottom sheet.
+
+## How it works
+
+To show a destination as a bottom sheet, you need to do two things:
+
+1.  **Use `BottomSheetSceneStrategy`**: Create an instance of `BottomSheetSceneStrategy` and pass it to the `sceneStrategy` parameter of the `NavDisplay` composable.
+
+2.  **Add metadata to the destination**: For the destination that you want to display as a bottom sheet, add `BottomSheetSceneStrategy.bottomSheet()` to its metadata. This is done in the `entry` function.
+
+In this example, `RouteB` is configured to be a bottom sheet. When you navigate from `RouteA` to `RouteB`, `RouteB` will be displayed in a modal bottom sheet that slides up from the bottom of the screen.
+
+The content of the bottom sheet can be styled as needed. In this recipe, the content is clipped to have rounded corners.
+
+For more information, see the official documentation on [custom layouts](https://developer.android.com/guide/navigation/navigation-3/custom-layouts).