reis-mobile 0.3.6 → 0.4.0

package/skills/android-navigation-3/references/android/guide/navigation/navigation-3/recipes/animations.md

@@ -0,0 +1,147 @@
+# 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.
+[![](https://developer.android.com/static/images/picto-icons/code.svg) Explore View the full recipe on GitHub.](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/animations)
+
+```
+package com.example.nav3recipes.animations
+
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.animation.EnterTransition
+import androidx.compose.animation.ExitTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.animation.slideInHorizontally
+import androidx.compose.animation.slideInVertically
+import androidx.compose.animation.slideOutHorizontally
+import androidx.compose.animation.slideOutVertically
+import androidx.compose.animation.togetherWith
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.metadata
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.content.ContentMauve
+import com.example.nav3recipes.content.ContentOrange
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.serialization.Serializable
+
+
+@Serializable
+private data object ScreenA : NavKey
+
+@Serializable
+private data object ScreenB : NavKey
+
+@Serializable
+private data object ScreenC : NavKey
+
+
+class AnimatedActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+        setContent {
+
+            val backStack = rememberNavBackStack(ScreenA)
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                entryProvider = entryProvider {
+                    entry<ScreenA> {
+                        ContentOrange("This is Screen A") {
+                            Button(onClick = dropUnlessResumed { backStack.add(ScreenB) }) {
+                                Text("Go to Screen B")
+                            }
+                        }
+                    }
+                    entry<ScreenB> {
+                        ContentMauve("This is Screen B") {
+                            Button(onClick = dropUnlessResumed { backStack.add(ScreenC) }) {
+                                Text("Go to Screen C")
+                            }
+                        }
+                    }
+                    entry<ScreenC>(
+                        metadata = metadata {
+                            // Slide new content up, keeping the old content in place underneath
+                            put(NavDisplay.TransitionKey) {
+                                slideInVertically(
+                                    initialOffsetY = { it },
+                                    animationSpec = tween(1000)
+                                ) togetherWith ExitTransition.KeepUntilTransitionsFinished
+                            }
+
+                            // Slide old content down, revealing the new content in place underneath
+                            put(NavDisplay.PopTransitionKey) {
+                                EnterTransition.None togetherWith
+                                        slideOutVertically(
+                                            targetOffsetY = { it },
+                                            animationSpec = tween(1000)
+                                        )
+                            }
+
+                            // Slide old content down, revealing the new content in place underneath
+                            put(NavDisplay.PredictivePopTransitionKey) {
+                                EnterTransition.None togetherWith
+                                        slideOutVertically(
+                                            targetOffsetY = { it },
+                                            animationSpec = tween(1000)
+                                        )
+                            }
+                        }
+                    ) {
+                        ContentGreen("This is Screen C")
+                    }
+                },
+                transitionSpec = {
+                    // Slide in from right when navigating forward
+                    slideInHorizontally(
+                        initialOffsetX = { it },
+                        animationSpec = tween(1000)
+                    ) togetherWith slideOutHorizontally(
+                        targetOffsetX = { -it },
+                        animationSpec = tween(1000)
+                    )
+                },
+                popTransitionSpec = {
+                    // Slide in from left when navigating back
+                    slideInHorizontally(
+                        initialOffsetX = { -it },
+                        animationSpec = tween(1000)
+                    ) togetherWith slideOutHorizontally(
+                        targetOffsetX = { it },
+                        animationSpec = tween(1000)
+                    )
+                },
+                predictivePopTransitionSpec = {
+                    // Slide in from left when navigating back
+                    slideInHorizontally(
+                        initialOffsetX = { -it },
+                        animationSpec = tween(1000)
+                    ) togetherWith slideOutHorizontally(
+                        targetOffsetX = { it },
+                        animationSpec = tween(1000)
+                    )
+                }
+            )
+        }
+    }
+}
+```

package/skills/android-navigation-3/references/android/guide/navigation/navigation-3/recipes/basic.md

@@ -0,0 +1,89 @@
+# 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.
+[![](https://developer.android.com/static/images/picto-icons/code.svg) Explore View the full recipe on GitHub.](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/basic)
+
+```
+/*
+ * 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.basic
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.compose.runtime.mutableStateListOf
+import androidx.compose.runtime.remember
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentBlue
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+
+private data object RouteA
+
+private data class RouteB(val id: String)
+
+class BasicActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+        setContent {
+            val backStack = remember { mutableStateListOf<Any>(RouteA) }
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                entryProvider = { key ->
+                    when (key) {
+                        is RouteA -> NavEntry(key) {
+                            ContentGreen("Welcome to Nav3") {
+                                Button(onClick = dropUnlessResumed {
+                                    backStack.add(RouteB("123"))
+                                }) {
+                                    Text("Click to navigate")
+                                }
+                            }
+                        }
+
+                        is RouteB -> NavEntry(key) {
+                            ContentBlue("Route id: ${key.id} ")
+                        }
+
+                        else -> {
+                            error("Unknown route: $key")
+                        }
+                    }
+                }
+            )
+        }
+    }
+}
+```

package/skills/android-navigation-3/references/android/guide/navigation/navigation-3/recipes/basicdsl.md

@@ -0,0 +1,85 @@
+# 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.
+[![](https://developer.android.com/static/images/picto-icons/code.svg) Explore View the full recipe on GitHub.](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/basicdsl)
+
+```
+/*
+ * 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.basicdsl
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentBlue
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.serialization.Serializable
+
+@Serializable
+private data object RouteA : NavKey
+
+@Serializable
+private data class RouteB(val id: String) : NavKey
+
+class BasicDslActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+        setContent {
+            val backStack = rememberNavBackStack(RouteA)
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                entryProvider = entryProvider {
+                    entry<RouteA> {
+                        ContentGreen("Welcome to Nav3") {
+                            Button(onClick = dropUnlessResumed {
+                                backStack.add(RouteB("123"))
+                            }) {
+                                Text("Click to navigate")
+                            }
+                        }
+                    }
+                    entry<RouteB> { key ->
+                        ContentBlue("Route id: ${key.id} ")
+                    }
+                }
+            )
+        }
+    }
+}
+```

package/skills/android-navigation-3/references/android/guide/navigation/navigation-3/recipes/basicsaveable.md

@@ -0,0 +1,90 @@
+# 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.
+[![](https://developer.android.com/static/images/picto-icons/code.svg) Explore View the full recipe on GitHub.](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/basicsaveable)
+
+```
+/*
+ * 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.basicsaveable
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentBlue
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.serialization.Serializable
+
+@Serializable
+private data object RouteA : NavKey
+
+@Serializable
+private data class RouteB(val id: String) : NavKey
+
+class BasicSaveableActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+        setContent {
+            val backStack = rememberNavBackStack(RouteA)
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                entryProvider = { key ->
+                    when (key) {
+                        is RouteA -> NavEntry(key) {
+                            ContentGreen("Welcome to Nav3") {
+                                Button(onClick = dropUnlessResumed {
+                                    backStack.add(RouteB("123"))
+                                }) {
+                                    Text("Click to navigate")
+                                }
+                            }
+                        }
+
+                        is RouteB -> NavEntry(key) {
+                            ContentBlue("Route id: ${key.id} ")
+                        }
+
+                        else -> {
+                            error("Unknown route: $key")
+                        }
+                    }
+                }
+            )
+        }
+    }
+}
+```

package/skills/android-navigation-3/references/android/guide/navigation/navigation-3/recipes/bottomsheet.md

@@ -0,0 +1,195 @@
+# 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).
+[![](https://developer.android.com/static/images/picto-icons/code.svg) Explore View the full recipe on GitHub.](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/bottomsheet)
+
+```
+/*
+ * 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.bottomsheet
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Button
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.Text
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.unit.dp
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentBlue
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.serialization.Serializable
+
+@Serializable
+private data object RouteA : NavKey
+
+@Serializable
+private data class RouteB(val id: String) : NavKey
+
+class BottomSheetActivity : ComponentActivity() {
+
+    @OptIn(ExperimentalMaterial3Api::class)
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+        setContent {
+            val backStack = rememberNavBackStack(RouteA)
+            val bottomSheetStrategy = remember { BottomSheetSceneStrategy<NavKey>() }
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                sceneStrategies = listOf(bottomSheetStrategy),
+                entryProvider = entryProvider {
+                    entry<RouteA> {
+                        ContentGreen("Welcome to Nav3") {
+                            Button(onClick = dropUnlessResumed {
+                                backStack.add(RouteB("123"))
+                            }) {
+                                Text("Click to open bottom sheet")
+                            }
+                        }
+                    }
+                    entry<RouteB>(
+                        metadata = BottomSheetSceneStrategy.bottomSheet()
+                    ) { key ->
+                        ContentBlue(
+                            title = "Route id: ${key.id}",
+                            modifier = Modifier.clip(
+                                shape = RoundedCornerShape(16.dp)
+                            )
+                        )
+                    }
+                }
+            )
+        }
+    }
+}
+```
+
+```
+package com.example.nav3recipes.bottomsheet
+
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.ModalBottomSheet
+import androidx.compose.material3.ModalBottomSheetProperties
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.lifecycle.compose.LocalLifecycleOwner
+import androidx.lifecycle.compose.rememberLifecycleOwner
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavMetadataKey
+import androidx.navigation3.runtime.get
+import androidx.navigation3.runtime.metadata
+import androidx.navigation3.scene.OverlayScene
+import androidx.navigation3.scene.Scene
+import androidx.navigation3.scene.SceneStrategy
+import androidx.navigation3.scene.SceneStrategyScope
+import com.example.nav3recipes.bottomsheet.BottomSheetSceneStrategy.Companion.bottomSheet
+
+/** An [OverlayScene] that renders an [entry] within a [ModalBottomSheet]. */
+@OptIn(ExperimentalMaterial3Api::class)
+internal data class BottomSheetScene<T : Any>(
+    override val key: T,
+    override val previousEntries: List<NavEntry<T>>,
+    override val overlaidEntries: List<NavEntry<T>>,
+    private val entry: NavEntry<T>,
+    private val modalBottomSheetProperties: ModalBottomSheetProperties,
+    private val onBack: () -> Unit,
+) : OverlayScene<T> {
+
+    override val entries: List<NavEntry<T>> = listOf(entry)
+
+    override val content: @Composable (() -> Unit) = {
+        val lifecycleOwner = rememberLifecycleOwner()
+        ModalBottomSheet(
+            onDismissRequest = onBack,
+            properties = modalBottomSheetProperties,
+        ) {
+            CompositionLocalProvider(LocalLifecycleOwner provides lifecycleOwner) {
+                entry.Content()
+            }
+        }
+    }
+}
+
+/**
+ * A [SceneStrategy] that displays entries that have added [bottomSheet] to their [NavEntry.metadata]
+ * within a [ModalBottomSheet] instance.
+ *
+ * This strategy should always be added before any non-overlay scene strategies.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+class BottomSheetSceneStrategy<T : Any> : SceneStrategy<T> {
+
+    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? {
+        val lastEntry = entries.lastOrNull() ?: return null
+        val bottomSheetProperties = lastEntry.metadata[BottomSheetKey] ?: return null
+        return bottomSheetProperties.let { properties ->
+            @Suppress("UNCHECKED_CAST")
+            BottomSheetScene(
+                key = lastEntry.contentKey as T,
+                previousEntries = entries.dropLast(1),
+                overlaidEntries = entries.dropLast(1),
+                entry = lastEntry,
+                modalBottomSheetProperties = properties,
+                onBack = onBack
+            )
+        }
+    }
+
+    companion object {
+        /**
+         * Function to be called on the [NavEntry.metadata] to mark this entry as something that
+         * should be displayed within a [ModalBottomSheet].
+         *
+         * @param modalBottomSheetProperties properties that should be passed to the containing
+         * [ModalBottomSheet].
+         */
+        fun bottomSheet(modalBottomSheetProperties: ModalBottomSheetProperties = ModalBottomSheetProperties()) =
+            metadata {
+                put(BottomSheetKey, modalBottomSheetProperties)
+            }
+
+        object BottomSheetKey : NavMetadataKey<ModalBottomSheetProperties>
+    }
+
+}
+```