Add recipes for returning navigation results

This commit adds two new recipes demonstrating how to return a result
from one screen to a previous one.

The "Return result as Event" recipe uses a `ResultStore` backed by
Kotlin `Channel`s. A screen can send a result, and the previous screen
can listen for it using a `ResultEffect` composable.

The "Return result as State" recipe uses a `rememberResult` composable,
which wraps `mutableStateOf`. The state is hoisted and can be updated
by a child screen.

Author: Jeremy Woods

app/src/main/AndroidManifest.xml

@@ -94,6 +94,16 @@
             android:exported="true"
             android:label="@string/app_name"
             android:theme="@style/Theme.Nav3Recipes"/>
+        <activity
+            android:name=".results.event.ResultEventActivity"
+            android:exported="true"
+            android:label="@string/app_name"
+            android:theme="@style/Theme.Nav3Recipes"/>
+        <activity
+            android:name=".results.state.ResultStateActivity"
+            android:exported="true"
+            android:label="@string/app_name"
+            android:theme="@style/Theme.Nav3Recipes"/>
     </application>
 
 </manifest>

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

@@ -35,6 +35,8 @@ import com.example.nav3recipes.dialog.DialogActivity
 import com.example.nav3recipes.modular.hilt.ModularActivity
 import com.example.nav3recipes.passingarguments.basicviewmodels.BasicViewModelsActivity
 import com.example.nav3recipes.passingarguments.injectedviewmodels.InjectedViewModelsActivity
+import com.example.nav3recipes.results.event.ResultEventActivity
+import com.example.nav3recipes.results.state.ResultStateActivity
 import com.example.nav3recipes.scenes.materiallistdetail.MaterialListDetailActivity
 import com.example.nav3recipes.scenes.twopane.TwoPaneActivity
 import com.example.nav3recipes.ui.setEdgeToEdgeConfig
@@ -71,6 +73,10 @@ private val recipes = listOf(
     Heading("Passing navigation arguments"),
     Recipe("Argument passing to basic ViewModel", BasicViewModelsActivity::class.java),
     Recipe("Argument passing to injected ViewModel", InjectedViewModelsActivity::class.java),
+
+    Heading("Returning Results"),
+    Recipe("Return result as Event", ResultEventActivity::class.java),
+    Recipe("Return result as State", ResultStateActivity::class.java),
 )
 
 class RecipePickerActivity : ComponentActivity() {

app/src/main/java/com/example/nav3recipes/results/event/ResultEffect.kt

@@ -0,0 +1,17 @@
+package com.example.nav3recipes.results.event
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+
+@Composable
+inline fun <reified T> ResultEffect(
+    resultStore: ResultStore = LocalResultStore.current,
+    resultKey: String = T::class.toString(),
+    crossinline onResult: suspend (T) -> Unit
+) {
+    LaunchedEffect(resultKey, resultStore.channelMap[resultKey]) {
+        resultStore.getResultFlow<T>()?.collect { result ->
+            onResult.invoke(result as T)
+        }
+    }
+}

app/src/main/java/com/example/nav3recipes/results/event/ResultEventActivity.kt

@@ -0,0 +1,109 @@
+/*
+ * 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.results.event
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.text.input.rememberTextFieldState
+import androidx.compose.material3.Button
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.ui.Modifier
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewmodel.compose.viewModel
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import kotlinx.serialization.Serializable
+
+@Serializable
+data object Home : NavKey
+
+@Serializable
+class ResultPage : NavKey
+
+class ResultEventActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            val resultStore = LocalResultStore.current
+
+            Scaffold { paddingValues ->
+
+                val backStack = rememberNavBackStack(Home)
+
+                NavDisplay(
+                    backStack = backStack,
+                    modifier = Modifier.padding(paddingValues),
+                    onBack = { backStack.removeLastOrNull() },
+                    entryProvider = { key ->
+                        when (key) {
+                            is Home -> NavEntry(key) {
+                                val viewModel = viewModel<HomeViewModel>(key = Home.toString())
+                                ResultEffect<Name?>(resultStore) { name ->
+                                    viewModel.name = name
+                                }
+
+                                Column {
+                                    Text("Welcome to Nav3")
+                                    Button(onClick = {
+                                        backStack.add(ResultPage())
+                                    }) {
+                                        Text("Click to navigate")
+                                    }
+                                    Text("My returned name is ${viewModel.name}")
+                                }
+
+
+                            }
+                            is ResultPage -> NavEntry(key) {
+                                Column {
+
+                                    val state = rememberTextFieldState()
+                                    OutlinedTextField(
+                                        state = state,
+                                        label = { Text("Result to Return") }
+                                    )
+                                    Button(onClick = {
+                                        resultStore.sendResult<Name>(result = state.text as String)
+                                        backStack.removeLastOrNull()
+                                    }) {
+                                        Text("Return result")
+                                    }
+                                }
+                            }
+                            else -> NavEntry(key) { Text("Unknown route") }
+                        }
+                    }
+                )
+            }
+        }
+    }
+}
+
+class HomeViewModel : ViewModel() {
+    var name: String? = null
+}
+
+typealias Name = String

app/src/main/java/com/example/nav3recipes/results/event/ResultStore.kt

@@ -0,0 +1,42 @@
+package com.example.nav3recipes.results.event
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.ProvidableCompositionLocal
+import androidx.compose.runtime.ProvidedValue
+import androidx.compose.runtime.compositionLocalOf
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.channels.Channel.Factory.BUFFERED
+import kotlinx.coroutines.flow.receiveAsFlow
+
+
+object LocalResultStore {
+    private val LocalResultStore: ProvidableCompositionLocal<ResultStore?>
+        get() {
+            return compositionLocalOf { null }
+        }
+
+    val current: ResultStore
+        @Composable
+        get() = LocalResultStore.current ?: ResultStore()
+
+    infix fun provides(
+        store: ResultStore
+    ): ProvidedValue<ResultStore?> {
+        return LocalResultStore.provides(store)
+    }
+}
+
+class ResultStore {
+    val channelMap: MutableMap<String, Channel<Any?>> = mutableMapOf()
+
+    inline fun <reified T> getResultFlow(resultKey: String = T::class.toString()) =
+        channelMap[resultKey]?.receiveAsFlow()
+
+    inline fun <reified T> sendResult(resultKey: String = T::class.toString(), result: T) {
+        if (!channelMap.contains(resultKey)) {
+            channelMap.put(resultKey, Channel(capacity = BUFFERED, onBufferOverflow = BufferOverflow.SUSPEND))
+        }
+        channelMap[resultKey]?.trySend(result)
+    }
+}

app/src/main/java/com/example/nav3recipes/results/state/Result.kt

@@ -0,0 +1,9 @@
+package com.example.nav3recipes.results.state
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+
+@Composable
+fun <T> rememberResult(defaultValue: T) =
+    remember { mutableStateOf(defaultValue) }.apply { value = defaultValue }

app/src/main/java/com/example/nav3recipes/results/state/ResultStateActivity.kt

@@ -0,0 +1,108 @@
+/*
+ * 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.results.state
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.text.input.rememberTextFieldState
+import androidx.compose.material3.Button
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewmodel.compose.viewModel
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import kotlinx.serialization.Serializable
+
+@Serializable
+data object Home : NavKey
+
+@Serializable
+class ResultPage : NavKey
+
+class ResultStateActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            Scaffold { paddingValues ->
+                var result by rememberResult<Name?>(defaultValue = null)
+                val backStack = rememberNavBackStack(Home)
+
+                NavDisplay(
+                    backStack = backStack,
+                    modifier = Modifier.padding(paddingValues),
+                    onBack = { backStack.removeLastOrNull() },
+                    entryProvider = { key ->
+                        when (key) {
+                            is Home -> NavEntry(key) {
+                                val viewModel = viewModel<HomeViewModel>(key = Home.toString())
+                                viewModel.name = result
+
+                                Column {
+                                    Text("Welcome to Nav3")
+                                    Button(onClick = {
+                                        backStack.add(ResultPage())
+                                    }) {
+                                        Text("Click to navigate")
+                                    }
+                                    Text("My returned name is ${viewModel.name}")
+                                }
+
+
+                            }
+                            is ResultPage -> NavEntry(key) {
+                                Column {
+
+                                    val state = rememberTextFieldState()
+                                    OutlinedTextField(
+                                        state = state,
+                                        label = { Text("Result to Return") }
+                                    )
+
+                                    Button(onClick = {
+                                        result = state.text as String
+                                        backStack.removeLastOrNull()
+                                    }) {
+                                        Text("Return result")
+                                    }
+                                }
+                            }
+                            else -> NavEntry(key) { Text("Unknown route") }
+                        }
+                    }
+                )
+            }
+        }
+    }
+}
+
+class HomeViewModel : ViewModel() {
+    var name: String? = null
+}
+
+typealias Name = String