feat: Add READMEs for all recipes

This commit adds a `README.md` file to each recipe package.

Each README explains the purpose of the specific recipe and details how it works, providing context and documentation for the example code.

Author: dturner

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/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/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/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/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).

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

@@ -0,0 +1,30 @@
+# Common UI Recipe
+
+This recipe demonstrates how to implement a common navigation UI pattern with a bottom navigation bar and multiple back stacks, where each tab in the navigation bar has its own navigation history.
+
+## How it works
+
+This example has three top-level destinations: Home, ChatList, and Camera. The ChatList destination also has a sub-route, ChatDetail.
+
+### `TopLevelBackStack`
+
+The core of this recipe is the `TopLevelBackStack` class, which is responsible for managing the navigation state. It works as follows:
+
+-   It maintains a separate back stack for each top-level destination (tab).
+-   It keeps track of the currently selected top-level destination.
+-   It provides a single, flattened back stack that can be used by the `NavDisplay` composable. This flattened back stack is a combination of the individual back stacks of all the tabs.
+
+### UI Structure
+
+The UI is built using a `Scaffold` composable, with a `NavigationBar` as the `bottomBar`.
+
+-   The `NavigationBar` displays an item for each top-level destination. When an item is clicked, it calls `topLevelBackStack.addTopLevel` to switch to the corresponding tab, preserving the navigation history of each tab.
+-   The `NavDisplay` composable is placed in the content area of the `Scaffold`. It is responsible for displaying the current screen based on the flattened back stack provided by `TopLevelBackStack`.
+
+This approach allows for a common navigation pattern where users can switch between different sections of the app, and each section maintains its own navigation history.
+
+### State Preservation
+
+It's important to note how the navigation state is managed in this recipe. When a user navigates away from a top-level destination (e.g., by pressing the back button until they return to a previous tab), the entire navigation history for that destination is cleared. The state is not saved. When the user returns to that tab later, they will start from its initial screen.
+
+**Note**: In this example, the Home route can move above the ChatList and Camera routes, meaning navigating back from Home doesn't necessarily leave the app. The app will exit when the user goes back from a single remaining top level route in the back stack.

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

@@ -0,0 +1,21 @@
+# Conditional Navigation Recipe
+
+This recipe demonstrates how to implement conditional navigation, where certain destinations are only accessible if a condition is met (in this case, if the user is logged in).
+
+## How it works
+
+This example has a `Profile` destination that requires the user to be logged in. If the user is not logged in and attempts to navigate to `Profile`, they are redirected to a `Login` screen. After a successful login, they are automatically navigated to the `Profile` screen.
+
+### `AppBackStack`
+
+The core of this recipe is the custom `AppBackStack` class, which encapsulates the logic for conditional navigation.
+
+-   **`RequiresLogin` interface**: A marker interface, `RequiresLogin`, is used to identify destinations that require the user to be logged in. The `Profile` destination implements this interface.
+
+-   **Redirecting to Login**: When the `add` function is called with a destination that implements `RequiresLogin` and the user is not logged in, `AppBackStack` stores the intended destination and adds the `Login` route to the back stack instead.
+
+-   **Handling Login**: When the `login` function is called, it sets the user's status to logged in. If there is a stored destination that the user was trying to access, it adds that destination to the back stack and removes the `Login` screen.
+
+-   **Handling Logout**: When the `logout` function is called, it sets the user's status to logged out and removes any destinations from the back stack that require the user to be logged in.
+
+This approach provides a clean way to handle conditional navigation by centralizing the logic in a custom back stack implementation.

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

@@ -0,0 +1,17 @@
+# Dialog Recipe
+
+This recipe demonstrates how to display a destination as a dialog.
+
+## How it works
+
+To show a destination as a dialog, you need to do two things:
+
+1.  **Use `DialogSceneStrategy`**: Create an instance of `DialogSceneStrategy` 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 dialog, add `DialogSceneStrategy.dialog()` to its metadata. This is done in the `entry` function. You can also pass a `DialogProperties` object to customize the dialog's behavior and appearance.
+
+In this example, `RouteB` is configured to be a dialog. When you navigate from `RouteA` to `RouteB`, `RouteB` will be displayed in a dialog window.
+
+The content of the dialog 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).

app/src/main/java/com/example/nav3recipes/material/listdetail/README.md

@@ -0,0 +1,20 @@
+# Material List-Detail Recipe
+
+This recipe demonstrates how to create an adaptive list-detail layout using the `ListDetailSceneStrategy` from the Material 3 Adaptive library. This layout automatically adjusts to show one, two, or three panes depending on the available screen width.
+
+## How it works
+
+This example has three destinations: `ConversationList`, `ConversationDetail`, and `Profile`.
+
+### `ListDetailSceneStrategy`
+
+The key to this recipe is the `rememberListDetailSceneStrategy`, which provides the logic for the adaptive layout.
+
+-   **Pane Roles**: Each destination is assigned a role using metadata:
+    -   `ListDetailSceneStrategy.listPane()`: For the primary (list) content. This pane is always visible. A placeholder can be provided to be shown in the detail pane area when no detail content is selected.
+    -   `ListDetailSceneStrategy.detailPane()`: For the secondary (detail) content.
+    -   `ListDetailSceneStrategy.extraPane()`: For tertiary content.
+
+-   **Adaptive Layout**: The `ListDetailSceneStrategy` automatically handles the layout. On smaller screens, only one pane is shown at a time. On wider screens, it will show the list and detail panes side-by-side. On very wide screens, it can show all three panes: list, detail, and extra.
+
+-   **Navigation**: Navigation between the panes is handled by adding and removing destinations from the back stack as usual. The `ListDetailSceneStrategy` observes the back stack and adjusts the layout accordingly.

app/src/main/java/com/example/nav3recipes/material/supportingpane/README.md

@@ -0,0 +1,22 @@
+# Material Supporting Pane Recipe
+
+This recipe demonstrates how to create an adaptive layout with a main pane and a supporting pane using the `SupportingPaneSceneStrategy` from the Material 3 Adaptive library. This layout is useful for displaying supplementary content alongside the main content on larger screens.
+
+## How it works
+
+This example has three destinations: `MainVideo`, `RelatedVideos`, and `Profile`.
+
+### `SupportingPaneSceneStrategy`
+
+The `rememberSupportingPaneSceneStrategy` provides the logic for this adaptive layout.
+
+-   **Pane Roles**: Each destination is assigned a role using metadata:
+    -   `SupportingPaneSceneStrategy.mainPane()`: For the primary content. This pane is always visible.
+    -   `SupportingPaneSceneStrategy.supportingPane()`: For the supplementary content. This pane is shown alongside the main pane on larger screens.
+    -   `SupportingPaneSceneStrategy.extraPane()`: For tertiary content that can be displayed alongside the supporting pane on even larger screens.
+
+-   **Adaptive Layout**: The `SupportingPaneSceneStrategy` automatically handles the layout. On smaller screens, only the main pane is shown. On larger screens, the supporting pane is shown next to the main pane.
+
+-   **Back Navigation**: The `BackNavigationBehavior` is customized in this example to `PopUntilCurrentDestinationChange`. This means that when the user presses the back button, the supporting pane will be dismissed, revealing the main pane underneath.
+
+-   **Navigation**: Navigation is handled by adding and removing destinations from the back stack. The `SupportingPaneSceneStrategy` observes these changes and adjusts the layout accordingly.