reis-mobile 0.3.6 → 0.4.0

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

@@ -0,0 +1,185 @@
+# LocalLifecycleOwner Recipe
+
+This recipe demonstrates how to use `LifecycleResumeEffect` in Navigation 3 entries to pause and resume work based on the entry's lifecycle state.
+
+## How it works
+
+In Navigation 3, by default each `NavEntry` is provided its own `LifecycleOwner` via `LocalLifecycleOwner.current`. This means that any lifecycle-aware components inside the entry is automatically scoped to the `NavEntry`.
+
+### `LifecycleResumeEffect` with Dialog Scenes
+
+1. **RouteA (Screen)**:
+
+   - Uses `LifecycleResumeEffect(Unit)` scoped to the `NavEntry`'s `LocalLifecycleOwner.current` to advance the`LinearProgressIndicator` while in the `RESUMED` state.
+   - Automatically resets `progressValue` back to `0f` whenever it hits `1f`.
+2. **RouteB (Dialog)**:
+
+   - Configured as a dialog using `DialogSceneStrategy.dialog()`.
+   - When the user opens the RouteB dialog, RouteA remains visible behind the dialog in the `STARTED` state (leaving `RESUMED`).
+   - `LifecycleResumeEffect` calls `onPauseOrDispose`, pausing the progress indicator.
+   - When the dialog is dismissed, RouteA returns to `RESUMED`, and `LifecycleResumeEffect` resumes the progress indicator automatically.
+
+[![](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/lifecycleowner)
+
+```
+/*
+ * Copyright 2026 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.lifecycleowner
+
+import android.os.Bundle
+import android.util.Log
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.animateFloatAsState
+import androidx.compose.animation.core.snap
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.Button
+import androidx.compose.material3.LinearProgressIndicator
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.compose.LifecycleEventEffect
+import androidx.lifecycle.compose.LifecycleResumeEffect
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.scene.DialogSceneStrategy
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.serialization.Serializable
+import kotlin.time.Duration.Companion.milliseconds
+
+@Serializable
+private data object RouteA : NavKey
+
+@Serializable
+private data object RouteB : NavKey
+
+class LifecycleOwnerActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+        setContent {
+            val backStack = rememberNavBackStack(RouteA)
+            val dialogStrategy = remember { DialogSceneStrategy<NavKey>() }
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = backStack::removeLastOrNull,
+                sceneStrategies = listOf(dialogStrategy),
+                entryProvider = entryProvider {
+                    entry<RouteA> {
+                        LogLifecycleEffect("ScreenA")
+                        ContentGreen("Screen A") {
+                            var progressValue by remember { mutableFloatStateOf(0f) }
+                            val coroutineScope = rememberCoroutineScope()
+
+                            val animatedProgress by animateFloatAsState(
+                                targetValue = progressValue,
+                                animationSpec = if (progressValue == 0f) snap() else tween(durationMillis = 100, easing = LinearEasing),
+                                label = "ProgressAnimation"
+                            )
+
+                            // LifecycleResumeEffect runs only while ScreenA is in the RESUMED state.
+                            // When the dialog opens, ScreenA transitions to PAUSED, which calls onPauseOrDispose.
+                            LifecycleResumeEffect(Unit) {
+                                val job = coroutineScope.launch {
+                                    while (true) {
+                                        delay(100.milliseconds)
+                                        progressValue += 0.01f
+                                        if (progressValue >= 1f) {
+                                            progressValue = 0f
+                                        }
+                                    }
+                                }
+                                onPauseOrDispose {
+                                    job.cancel()
+                                }
+                            }
+
+                            Column(
+                                horizontalAlignment = Alignment.CenterHorizontally,
+                                modifier = Modifier.padding(16.dp)
+                            ) {
+                                LinearProgressIndicator(progress = { animatedProgress })
+                                Spacer(modifier = Modifier.height(16.dp))
+                                Button(onClick = dropUnlessResumed { backStack.add(RouteB) }) {
+                                    Text("Open Dialog")
+                                }
+                            }
+                        }
+                    }
+                    entry<RouteB>(metadata = DialogSceneStrategy.dialog()) {
+                        LogLifecycleEffect("Dialog")
+                        AlertDialog(
+                            onDismissRequest = backStack::removeLastOrNull,
+                            title = { Text("Dialog") },
+                            text = {
+                                Text("Screen A is no longer in resumed state, pausing the progress indicator.")
+                            },
+                            confirmButton = {
+                                Button(onClick = dropUnlessResumed { backStack.removeLastOrNull() }) {
+                                    Text("Dismiss Dialog")
+                                }
+                            }
+                        )
+                    }
+                }
+            )
+        }
+    }
+}
+
+@Composable
+private fun LogLifecycleEffect(screenName: String) {
+    LifecycleEventEffect(Lifecycle.Event.ON_CREATE) {
+        Log.d("LifecycleOwner", "$screenName: ON_CREATE")
+    }
+    LifecycleEventEffect(Lifecycle.Event.ON_START) {
+        Log.d("LifecycleOwner", "$screenName: ON_START")
+    }
+    LifecycleEventEffect(Lifecycle.Event.ON_RESUME) {
+        Log.d("LifecycleOwner", "$screenName: ON_RESUME")
+    }
+    LifecycleEventEffect(Lifecycle.Event.ON_PAUSE) {
+        Log.d("LifecycleOwner", "$screenName: ON_PAUSE")
+    }
+    LifecycleEventEffect(Lifecycle.Event.ON_STOP) {
+        Log.d("LifecycleOwner", "$screenName: ON_STOP")
+    }
+    // Note that ON_DESTROY event is not observable from composables.
+}
+```

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

@@ -0,0 +1,141 @@
+# 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.
+
+[![](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/material/listdetail)
+
+```
+package com.example.nav3recipes.material.listdetail
+
+/*
+ * 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.
+ */
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.Column
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.compose.material3.adaptive.ExperimentalMaterial3AdaptiveApi
+import androidx.compose.material3.adaptive.currentWindowAdaptiveInfoV2
+import androidx.compose.material3.adaptive.layout.calculatePaneScaffoldDirective
+import androidx.compose.material3.adaptive.navigation3.ListDetailSceneStrategy
+import androidx.compose.material3.adaptive.navigation3.rememberListDetailSceneStrategy
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Alignment
+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.content.ContentRed
+import com.example.nav3recipes.content.ContentYellow
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.serialization.Serializable
+
+@Serializable
+private object ConversationList : NavKey
+
+@Serializable
+private data class ConversationDetail(val id: String) : NavKey
+
+@Serializable
+private data object Profile : NavKey
+
+class MaterialListDetailActivity : ComponentActivity() {
+
+    @OptIn(ExperimentalMaterial3AdaptiveApi::class)
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+
+        setContent {
+
+            val backStack = rememberNavBackStack(ConversationList)
+
+            // Override the defaults so that there isn't a horizontal space between the panes.
+            // See b/418201867
+            val windowAdaptiveInfo = currentWindowAdaptiveInfoV2()
+            val directive = remember(windowAdaptiveInfo) {
+                calculatePaneScaffoldDirective(windowAdaptiveInfo)
+                    .copy(horizontalPartitionSpacerSize = 0.dp)
+            }
+            val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>(directive = directive)
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                sceneStrategies = listOf(listDetailStrategy),
+                entryProvider = entryProvider {
+                    entry<ConversationList>(
+                        metadata = ListDetailSceneStrategy.listPane(
+                            detailPlaceholder = {
+                                ContentYellow("Choose a conversation from the list")
+                            }
+                        )
+                    ) {
+                        ContentRed("Welcome to Nav3") {
+                            Button(onClick = dropUnlessResumed {
+                                backStack.add(ConversationDetail("ABC"))
+                            }) {
+                                Text("View conversation")
+                            }
+                        }
+                    }
+                    entry<ConversationDetail>(
+                        metadata = ListDetailSceneStrategy.detailPane()
+                    ) { conversation ->
+                        ContentBlue("Conversation ${conversation.id} ") {
+                            Column(horizontalAlignment = Alignment.CenterHorizontally) {
+                                Button(onClick = dropUnlessResumed {
+                                    backStack.add(Profile)
+                                }) {
+                                    Text("View profile")
+                                }
+                            }
+                        }
+                    }
+                    entry<Profile>(
+                        metadata = ListDetailSceneStrategy.extraPane()
+                    ) {
+                        ContentGreen("Profile")
+                    }
+                }
+            )
+        }
+    }
+}
+```

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

@@ -0,0 +1,145 @@
+# 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.
+
+[![](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/material/supportingpane)
+
+```
+package com.example.nav3recipes.material.supportingpane
+
+/*
+ * 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.
+ */
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.Column
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.compose.material3.adaptive.ExperimentalMaterial3AdaptiveApi
+import androidx.compose.material3.adaptive.currentWindowAdaptiveInfoV2
+import androidx.compose.material3.adaptive.layout.calculatePaneScaffoldDirective
+import androidx.compose.material3.adaptive.navigation.BackNavigationBehavior
+import androidx.compose.material3.adaptive.navigation3.SupportingPaneSceneStrategy
+import androidx.compose.material3.adaptive.navigation3.rememberSupportingPaneSceneStrategy
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Alignment
+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.content.ContentRed
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.serialization.Serializable
+
+@Serializable
+private object MainVideo : NavKey
+
+@Serializable
+private data object RelatedVideos : NavKey
+
+@Serializable
+private data object Profile : NavKey
+
+class MaterialSupportingPaneActivity : ComponentActivity() {
+
+    @OptIn(ExperimentalMaterial3AdaptiveApi::class)
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+
+        setContent {
+
+            val backStack = rememberNavBackStack(MainVideo)
+
+            // Override the defaults so that there isn't a horizontal or vertical space between the panes.
+            // See b/444438086
+            val windowAdaptiveInfo = currentWindowAdaptiveInfoV2()
+            val directive = remember(windowAdaptiveInfo) {
+                calculatePaneScaffoldDirective(windowAdaptiveInfo)
+                    .copy(horizontalPartitionSpacerSize = 0.dp, verticalPartitionSpacerSize = 0.dp)
+            }
+
+            // Override the defaults so that the supporting pane can be dismissed by pressing back.
+            // See b/445826749
+            val supportingPaneStrategy = rememberSupportingPaneSceneStrategy<NavKey>(
+                backNavigationBehavior = BackNavigationBehavior.PopUntilCurrentDestinationChange,
+                directive = directive
+            )
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                sceneStrategies = listOf(supportingPaneStrategy),
+                entryProvider = entryProvider {
+                    entry<MainVideo>(
+                        metadata = SupportingPaneSceneStrategy.mainPane()
+                    ) {
+                        ContentRed("Video content") {
+                            Button(onClick = dropUnlessResumed {
+                                backStack.add(RelatedVideos)
+                            }) {
+                                Text("View related videos")
+                            }
+                        }
+                    }
+                    entry<RelatedVideos>(
+                        metadata = SupportingPaneSceneStrategy.supportingPane()
+                    ) {
+                        ContentBlue("Related videos") {
+                            Column(horizontalAlignment = Alignment.CenterHorizontally) {
+                                Button(onClick = dropUnlessResumed {
+                                    backStack.add(Profile)
+                                }) {
+                                    Text("View profile")
+                                }
+                            }
+                        }
+                    }
+                    entry<Profile>(
+                        metadata = SupportingPaneSceneStrategy.extraPane()
+                    ) {
+                        ContentGreen("Profile")
+                    }
+                }
+            )
+        }
+    }
+}
+```