@3fn/core 14.1.0 → 15.0.0

package/dist/consumer-canonical/skills/navigation-3/references/android/guide/navigation/navigation-3/recipes/conditional.md

@@ -0,0 +1,230 @@
+# 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.
+[![](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/conditional)
+
+```
+/*
+ * 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.conditional
+
+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.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.rememberSaveable
+import androidx.compose.runtime.saveable.rememberSerializable
+import androidx.compose.runtime.setValue
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavBackStack
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.serialization.NavBackStackSerializer
+import androidx.navigation3.runtime.serialization.NavKeySerializer
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentBlue
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.content.ContentYellow
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import kotlinx.serialization.Serializable
+
+
+/**
+ * Class for representing navigation keys in the app.
+ *
+ * Note: We use a sealed class because KotlinX Serialization handles
+ * polymorphic serialization of sealed classes automatically.
+ *
+ * @param requiresLogin - true if the navigation key requires that the user is logged in
+ * to navigate to it
+ */
+@Serializable
+sealed class ConditionalNavKey(val requiresLogin: Boolean = false) : NavKey
+
+/**
+ * Key representing home screen
+ */
+@Serializable
+private data object Home : ConditionalNavKey()
+
+/**
+ * Key representing profile screen that is only accessible once the user has logged in
+ */
+@Serializable
+private data object Profile : ConditionalNavKey(requiresLogin = true)
+
+/**
+ * Key representing login screen
+ *
+ * @param redirectToKey - navigation key to redirect to after successful login
+ */
+@Serializable
+private data class Login(
+    val redirectToKey: ConditionalNavKey? = null
+) : ConditionalNavKey()
+
+class ConditionalActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+        setContent {
+
+            val backStack = rememberNavBackStack<ConditionalNavKey>(Home)
+            var isLoggedIn by rememberSaveable {
+                mutableStateOf(false)
+            }
+            val navigator = remember {
+                Navigator(
+                    backStack = backStack,
+                    onNavigateToRestrictedKey = { redirectToKey -> Login(redirectToKey) },
+                    isLoggedIn = { isLoggedIn }
+                )
+            }
+
+            NavDisplay(
+                backStack = backStack,
+                onBack = { navigator.goBack() },
+                entryProvider = entryProvider {
+                    entry<Home> {
+                        ContentGreen("Welcome to Nav3. Logged in? ${isLoggedIn}") {
+                            Column {
+                                Button(onClick = dropUnlessResumed { navigator.navigate(Profile) }) {
+                                    Text("Profile")
+                                }
+                                Button(onClick = dropUnlessResumed { navigator.navigate(Login()) }) {
+                                    Text("Login")
+                                }
+                            }
+                        }
+                    }
+                    entry<Profile> {
+                        ContentBlue("Profile screen (only accessible once logged in)") {
+                            Button(onClick = dropUnlessResumed {
+                                isLoggedIn = false
+                                navigator.navigate(Home)
+                            }) {
+                                Text("Logout")
+                            }
+                        }
+                    }
+                    entry<Login> { key ->
+                        ContentYellow("Login screen. Logged in? $isLoggedIn") {
+                            Button(onClick = dropUnlessResumed {
+                                isLoggedIn = true
+                                key.redirectToKey?.let { targetKey ->
+                                    backStack.remove(key)
+                                    navigator.navigate(targetKey)
+                                }
+                            }) {
+                                Text("Login")
+                            }
+                        }
+                    }
+                }
+            )
+        }
+    }
+}
+
+
+// An overload of `rememberNavBackStack` that returns a subtype of `NavKey`.
+// See https://issuetracker.google.com/issues/463382671 for a discussion of this function
+@Composable
+fun <T : NavKey> rememberNavBackStack(vararg elements: T): NavBackStack<T> {
+    return rememberSerializable(
+        serializer = NavBackStackSerializer(elementSerializer = NavKeySerializer())
+    ) {
+        NavBackStack(*elements)
+    }
+}
+```
+
+```
+/*
+ * 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.conditional
+
+import androidx.navigation3.runtime.NavBackStack
+
+/**
+ * Provides navigation events with built-in support for conditional access. If the user attempts to
+ * navigate to a [ConditionalNavKey] that requires login ([ConditionalNavKey.requiresLogin] is true)
+ * but is not currently logged in, the Navigator will redirect the user to a login key.
+ *
+ * @property backStack The back stack that is modified by this class
+ * @property onNavigateToRestrictedKey A lambda that is called when the user attempts to navigate
+ * to a key that requires login. This should return the key that represents the login screen. The
+ * user's target key is supplied as a parameter so that after successful login the user can be
+ * redirected to their target destination.
+ * @property isLoggedIn A lambda that returns whether the user is logged in.
+ */
+class Navigator(
+    private val backStack: NavBackStack<ConditionalNavKey>,
+    private val onNavigateToRestrictedKey: (targetKey: ConditionalNavKey?) -> ConditionalNavKey,
+    private val isLoggedIn: () -> Boolean,
+) {
+    fun navigate(key: ConditionalNavKey) {
+        if (key.requiresLogin && !isLoggedIn()) {
+            val loginKey = onNavigateToRestrictedKey(key)
+            backStack.add(loginKey)
+        } else {
+            backStack.add(key)
+        }
+    }
+
+    fun goBack() = backStack.removeLastOrNull()
+}
+```

package/dist/consumer-canonical/skills/navigation-3/references/android/guide/navigation/navigation-3/recipes/deeplinks-advanced.md

@@ -0,0 +1,155 @@
+# Deep Link Advanced Recipe
+
+This recipe demonstrates how to apply the principles of navigation in the context of deep links by
+managing a synthetic backStack and Task stacks.
+
+# Recipe Structure
+
+This recipe simulates a real-world scenario where "App A" deeplinks
+into "App B".
+
+"App A" is simulated by the module [com.example.nav3recipes.deeplink.advanced](https://developer.android.com/app/src/main/java/com/example/nav3recipes/deeplink/advanced), which
+contains the `CreateAdvancedDeepLinkActivity` that allows you to create a deeplink intent and
+trigger that in either the existing Task, or in a new Task.
+
+"App B" is simulated by the module [advanceddeeplinkapp](https://developer.android.com/advanceddeeplinkapp/src/main/java/com/example/nav3recipes/deeplink/advanced), which contains
+the MainActivity that you deeplink into. That module shows you how to build a synthetic backStack
+and how to manage the Task stack properly in order to support both Back and Up buttons.
+
+# Core implementation
+
+The core helper functions for navigateUp and building synthetic backStack can be
+found [here](https://developer.android.com/static/advanceddeeplinkapp/src/main/java/com/example/nav3recipes/deeplink/advanced/util/DeepLinkBackStackUtil.kt)
+
+# Further Read
+
+Check out the [deep link guide](https://developer.android.com/docs/deeplink-guide) for a
+comprehensive guide on Deep linking principles and how to apply them in Navigation 3.
+[![](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/deeplink/advanced)
+
+```
+package com.example.nav3recipes.deeplink.advanced
+
+import android.content.Intent
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.core.net.toUri
+import androidx.lifecycle.compose.dropUnlessResumed
+import com.example.nav3recipes.common.deeplink.EntryScreen
+import com.example.nav3recipes.common.deeplink.LIST_FIRST_NAMES
+import com.example.nav3recipes.common.deeplink.LIST_LOCATIONS
+import com.example.nav3recipes.common.deeplink.MenuDropDown
+import com.example.nav3recipes.common.deeplink.PaddedButton
+import com.example.nav3recipes.common.deeplink.TextContent
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+
+internal const val ADVANCED_PATH_BASE = "https://www.nav3deeplink.com"
+
+/**
+ * The recipe entry point that allows users to create a deep link and make a request with it.
+ *
+ * **HOW THIS RECIPE WORKS** This recipe simulates a real-world scenario where "App A" deeplinks
+ * into "App B".
+ *
+ * "App A" is simulated by this current module [com.example.nav3recipes.deeplink.advanced], which
+ * contains the [AdvancedCreateDeepLinkActivity] that allows you to create a deeplink intent and
+ * trigger that in either the existing Task, or in a new Task.
+ *
+ * "App B" is simulated by the module [com.example.nav3recipes.deeplink.advanced], which contains
+ * the MainActivity that you deeplink into. That module shows you how to build a synthetic backStack
+ * and how to manage the Task stack properly in order to support both Back and Up buttons.
+ *
+ * See the [README](README.md) file of current module for more info on advanced deep linking.
+ */
+class AdvancedCreateDeepLinkActivity: ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            EntryScreen("Sandbox - Build Your Deeplink Intent") {
+                val initFirstName = MENU_OPTIONS_FIRST_NAME.values.first().first()
+                val initLocation = MENU_OPTIONS_LOCATION.values.last().first()
+                val initTaskStack = MENU_OPTIONS_TASK_STACK.values.first().first()
+                var firstName by remember { mutableStateOf(initFirstName) }
+                var location by remember { mutableStateOf(initLocation) }
+                var taskStack by remember { mutableStateOf(initTaskStack) }
+
+                // select first name
+                MenuDropDown(
+                    menuOptions = MENU_OPTIONS_FIRST_NAME,
+                ) { _, selected ->
+                    firstName = selected
+                }
+
+                // select first name
+                MenuDropDown(
+                    menuOptions = MENU_OPTIONS_LOCATION,
+                ) { _, selected ->
+                    location = selected
+                }
+
+                // select current task stack or build new task stack
+                MenuDropDown(
+                    menuOptions = MENU_OPTIONS_TASK_STACK,
+                ) { _, selected ->
+                    taskStack = selected
+                }
+
+                // build final deeplink URL and Intent
+                val finalUrl = "${ADVANCED_PATH_BASE}/user/$firstName/$location"
+
+                // display Intent info
+                val flagString = if (taskStack == TAG_NEW_TASK) {
+                    "Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK"
+                } else "<none>"
+                val intentString = """
+                    | Final Intent:
+                    | data = "$finalUrl"
+                    | action = Intent.ACTION_VIEW
+                    | flags = $flagString
+                """.trimMargin()
+
+                TextContent(intentString)
+
+                // deeplink to target
+                PaddedButton("Deeplink Away!", onClick = dropUnlessResumed {
+                    val intent = Intent().apply {
+                        data = finalUrl.toUri()
+                        action = Intent.ACTION_VIEW
+                        if (taskStack == TAG_NEW_TASK) {
+                            flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
+                        }
+                    }
+
+                    startActivity(intent)
+                })
+            }
+        }
+    }
+}
+
+private const val TAG_FIRST_NAME = "firstName"
+private const val TAG_LOCATION = "location"
+private const val TAG_TASK_STACK = "Task stack"
+private const val TAG_CURRENT_TASK = "Use Current Task Stack"
+private const val TAG_NEW_TASK = "Start New Task Stack"
+
+private val MENU_OPTIONS_FIRST_NAME = mapOf(
+    TAG_FIRST_NAME to LIST_FIRST_NAMES
+)
+
+private val MENU_OPTIONS_LOCATION = mapOf(
+    TAG_LOCATION to LIST_LOCATIONS
+)
+
+private val MENU_OPTIONS_TASK_STACK = mapOf(
+    TAG_TASK_STACK to listOf(TAG_CURRENT_TASK, TAG_NEW_TASK),
+)
+```