Address the simpler feedbacks

claraf3 · claraf3 · commit 03bc8698bc70 · 2025-10-24T13:46:08.000-07:00
Rename activites, classes, and parameters.
diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
@@ -141,12 +141,12 @@
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes"/>
         <activity
-            android:name=".deeplink.parseintent.singleModule.ParseIntentLandingActivity"
+            android:name=".deeplink.parseintent.singleModule.CreateDeepLinkActivity"
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes">
         </activity>
         <activity
-            android:name=".deeplink.parseintent.singleModule.ParseIntentActivity"
+            android:name=".deeplink.parseintent.singleModule.MainActivity"
             android:exported="true"
             android:theme="@style/Theme.Nav3Recipes">
             <intent-filter android:autoVerify="true">
diff --git a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt
@@ -31,7 +31,7 @@ import com.example.nav3recipes.basicdsl.BasicDslActivity
 import com.example.nav3recipes.basicsaveable.BasicSaveableActivity
 import com.example.nav3recipes.commonui.CommonUiActivity
 import com.example.nav3recipes.conditional.ConditionalActivity
-import com.example.nav3recipes.deeplink.parseintent.singleModule.ParseIntentLandingActivity
+import com.example.nav3recipes.deeplink.parseintent.singleModule.CreateDeepLinkActivity
 import com.example.nav3recipes.dialog.DialogActivity
 import com.example.nav3recipes.modular.hilt.ModularActivity
 import com.example.nav3recipes.passingarguments.viewmodels.basic.BasicViewModelsActivity
@@ -84,7 +84,7 @@ private val recipes = listOf(
     Recipe("Return result as State", ResultStateActivity::class.java),
 
     Heading("Deeplink"),
-    Recipe("Parse Intent", ParseIntentLandingActivity::class.java),
+    Recipe("Parse Intent", CreateDeepLinkActivity::class.java),
 )
 
 class RecipePickerActivity : ComponentActivity() {
diff --git a/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CommonScreens.kt b/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CommonScreens.kt
@@ -32,13 +32,53 @@ import androidx.compose.ui.unit.TextUnit
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import androidx.core.net.toUri
+import androidx.navigation3.runtime.NavKey
+import kotlinx.serialization.Serializable
+
+internal interface NavRecipeKey: NavKey {
+    val name: String
+}
+
+@Serializable
+internal object HomeKey: NavRecipeKey {
+    override val name: String = STRING_LITERAL_HOME
+}
+
+@Serializable
+internal data class UsersKey(
+    val filter: String,
+): NavRecipeKey {
+    override val name: String = STRING_LITERAL_USERS
+    companion object {
+        const val FILTER_KEY = STRING_LITERAL_FILTER
+        const val FILTER_OPTION_RECENTLY_ADDED = "recentlyAdded"
+        const val FILTER_OPTION_ALL = "all"
+    }
+}
+
+@Serializable
+internal data class SearchKey(
+    val firstName: String? = null,
+    val ageMin: Int? = null,
+    val ageMax: Int? = null,
+    val location: String? = null,
+): NavRecipeKey {
+    override val name: String = STRING_LITERAL_SEARCH
+}
+
+@Serializable
+internal data class User(
+    val firstName: String,
+    val age: Int,
+    val location: String,
+)
 
 @Composable
-internal fun EntryScreen(text: String, block: @Composable () -> Unit = { }) {
+internal fun EntryScreen(text: String, content: @Composable () -> Unit = { }) {
     Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
         Column(horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.spacedBy(10.dp)) {
             Text(text, fontWeight = FontWeight.Bold, fontSize = FONT_SIZE_TITLE)
-            block()
+            content()
         }
     }
 }
diff --git a/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CreateDeepLinkActivity.kt b/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CreateDeepLinkActivity.kt
@@ -11,12 +11,11 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 
 /**
- * Landing page for this recipe. It displays several options users can choose from to formulate
- * the final deeplink request.
+ * This activity allows the user to create a deep link and make a request with it
  *
- * See [ParseIntentActivity] for how the requested deeplink is handled.
+ * See [MainActivity] for how the requested deeplink is handled.
  */
-class ParseIntentLandingActivity : ComponentActivity() {
+class CreateDeepLinkActivity : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
 
@@ -111,8 +110,8 @@ class ParseIntentLandingActivity : ComponentActivity() {
                 TextContent("Final url:\n$finalUrl")
                 // deeplink to target
                 DeepLinkButton(
-                    context = this@ParseIntentLandingActivity,
-                    targetActivity = ParseIntentActivity::class.java,
+                    context = this@CreateDeepLinkActivity,
+                    targetActivity = MainActivity::class.java,
                     deepLinkUrl = finalUrl
                 )
             }
diff --git a/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/DeepLinkUtil.kt b/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/DeepLinkUtil.kt
@@ -40,19 +40,19 @@ internal class DeepLinkRequest(
      *
      * returns a [DeepLinkMatchResult] if this matches the candidate, returns null otherwise
      */
-    fun <T : NavRecipeKey> match(deepLink: DeepLink<T>): DeepLinkMatchResult<T>? {
-        if (pathSegments.size != deepLink.pathSegments.size) return null
+    fun <T : NavRecipeKey> match(deepLinkPattern: DeepLinkPattern<T>): DeepLinkMatchResult<T>? {
+        if (pathSegments.size != deepLinkPattern.pathSegments.size) return null
         // exact match (url does not contain any arguments)
-        if (uri == deepLink.uriPattern)
-            return DeepLinkMatchResult(deepLink.serializer, mapOf())
+        if (uri == deepLinkPattern.uriPattern)
+            return DeepLinkMatchResult(deepLinkPattern.serializer, mapOf())
 
         val args = mutableMapOf<String, Any>()
         // match the path
         pathSegments
             .asSequence()
             // zip to compare the two objects side by side, order matters here so we
             // need to make sure the compared segments are at the same position within the url
-            .zip(deepLink.pathSegments.asSequence())
+            .zip(deepLinkPattern.pathSegments.asSequence())
             .forEach { it ->
                 // retrieve the two path segments to compare
                 val requestedSegment = it.first
@@ -75,7 +75,7 @@ internal class DeepLinkRequest(
         // match queries (if any)
         queries.forEach { query ->
             val name = query.key
-            val queryStringParser = deepLink.queryValueParsers[name]
+            val queryStringParser = deepLinkPattern.queryValueParsers[name]
             val queryParsedValue = try {
                 queryStringParser!!.invoke(query.value)
             } catch (e: IllegalArgumentException) {
@@ -85,7 +85,7 @@ internal class DeepLinkRequest(
             args[name] = queryParsedValue
         }
         // provide the serializer of the matching key and map of arg names to parsed arg values
-        return DeepLinkMatchResult(deepLink.serializer, args)
+        return DeepLinkMatchResult(deepLinkPattern.serializer, args)
     }
 }
 
@@ -98,16 +98,16 @@ internal class DeepLinkRequest(
  * supports deeplink. This means that if this deeplink contains any arguments (path or query),
  * the argument name must match any of [T] member field name.
  *
- * One [DeepLink] should be created for each supported deeplink. This means if [T]
+ * One [DeepLinkPattern] should be created for each supported deeplink. This means if [T]
  * supports two deeplink patterns:
  * ```
  *  val deeplink1 = www.nav3recipes.com/home
  *  val deeplink2 = www.nav3recipes.com/profile/{userId}
  *  ```
- * Then two [DeepLink] should be created
+ * Then two [DeepLinkPattern] should be created
  * ```
- * val parsedDeeplink1 = DeepLinkCandidate(T.serializer(), deeplink1)
- * val parsedDeeplink2 = DeepLinkCandidate(T.serializer(), deeplink2)
+ * val parsedDeeplink1 = DeepLinkPattern(T.serializer(), deeplink1)
+ * val parsedDeeplink2 = DeepLinkPattern(T.serializer(), deeplink2)
  * ```
  *
  * This implementation assumes a few things:
@@ -118,7 +118,7 @@ internal class DeepLinkRequest(
  * @param serializer the serializer of [T]
  * @param uriPattern the supported deeplink's uri pattern, i.e. "abc.com/home/{pathArg}"
  */
-internal class DeepLink<T : NavRecipeKey>(
+internal class DeepLinkPattern<T : NavRecipeKey>(
     val serializer: KSerializer<T>,
     val uriPattern: Uri
 ) {
@@ -268,7 +268,9 @@ private fun getTypeParser(kind: SerialKind): TypeParser {
         PrimitiveKind.FLOAT -> String::toFloat
         PrimitiveKind.LONG -> toLong
         PrimitiveKind.SHORT -> toShort
-        else -> Any::toString
+        else -> throw IllegalArgumentException(
+            "Unsupported argument type of SerialKind:$kind. The argument type must be a Primitive."
+        )
     }
 }
 
diff --git a/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/MainActivity.kt b/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/MainActivity.kt
@@ -0,0 +1,112 @@
+package com.example.nav3recipes.deeplink.parseintent.singleModule
+
+import android.net.Uri
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.core.net.toUri
+import androidx.navigation3.runtime.NavBackStack
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+
+/**
+ * Parses a target deeplink into a NavKey. There are several crucial steps involved:
+ *
+ * STEP 1.Parse supported deeplinks (URLs that can be deeplinked into) into a readily readable
+ *  format (see [DeepLinkPattern])
+ * STEP 2. Parse the requested deeplink into a readily readable, format (see [DeepLinkRequest])
+ *  **note** the parsed requested deeplink and parsed supported deeplinks should be cohesive with each
+ *  other to facilitate comparison and finding a match
+ * STEP 3. Compare the requested deeplink target with supported deeplinks in order to find a match
+ *  (see [DeepLinkMatchResult]). The match result's format should enable conversion from result
+ *  to backstack key, regardless of what the conversion method may be.
+ * STEP 4. Associate the match results with the correct backstack key
+ *
+ * This recipes provides an example for each of the above steps by way of kotlinx.serialization.
+ *
+ * **This recipe is designed to focus on parsing an intent into a key, and therefore these additional
+ * deeplink considerations are not included in this scope**
+ *  - Create synthetic backStack
+ *  - Multi-modular setup
+ *  - DI
+ *  - Managing TaskStack
+ *  - Up button ves Back Button
+ *
+ */
+class MainActivity : ComponentActivity() {
+    /** STEP 1. Parse supported deeplinks */
+    private val deepLinkPatterns: List<DeepLinkPattern<out NavRecipeKey>> = listOf(
+        // "https://www.nav3recipes.com/home"
+        DeepLinkPattern(HomeKey.serializer(), (URL_HOME_EXACT).toUri()),
+        // "https://www.nav3recipes.com/users/with/{filter}"
+        DeepLinkPattern(UsersKey.serializer(), (URL_USERS_WITH_FILTER).toUri()),
+        // "https://www.nav3recipes.com/users/search?{firstName}&{age}&{location}"
+        DeepLinkPattern(SearchKey.serializer(), (URL_SEARCH.toUri())),
+    )
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        // retrieve the target Uri
+        val uri: Uri? = intent.data
+        // associate the target with the correct backstack key
+        val key: NavKey = uri?.let {
+            /** STEP 2. Parse requested deeplink */
+            val target = DeepLinkRequest(uri)
+            /** STEP 3. Compared requested with supported deeplink to find match*/
+            val match = deepLinkPatterns.firstNotNullOfOrNull { candidate ->
+                target.match(candidate)
+            }
+            /** STEP 4. If match is found, associate match to the correct key*/
+            match?.let {
+                   //leverage kotlinx.serialization's Decoder to decode
+                   // match result into a backstack key
+                    KeyDecoder(match.args)
+                        .decodeSerializableValue(match.serializer)
+            }
+        } ?: HomeKey // fallback if intent.uri is null or match is not found
+
+        /**
+         * Then pass starting key to backstack
+         */
+        setContent {
+            val backStack: NavBackStack<NavKey> = rememberNavBackStack(key)
+            NavDisplay(
+                backStack = backStack,
+                onBack = { backStack.removeLastOrNull() },
+                entryProvider = entryProvider {
+                    entry<HomeKey> { key ->
+                        EntryScreen(key.name) {
+                            TextContent("<matches exact url>")
+                        }
+                    }
+                    entry<UsersKey> { key ->
+                        EntryScreen("${key.name} : ${key.filter}") {
+                            TextContent("<matches path argument>")
+                            val list = when {
+                                key.filter.isEmpty() -> LIST_USERS
+                                key.filter == UsersKey.FILTER_OPTION_ALL -> LIST_USERS
+                                else -> LIST_USERS.take(5)
+                            }
+                            FriendsList(list)
+                        }
+                    }
+                    entry<SearchKey> { search ->
+                        EntryScreen(search.name) {
+                            TextContent("<matches query parameters, if any>")
+                            val matchingUsers = LIST_USERS.filter { user ->
+                                (search.firstName == null || user.firstName == search.firstName) &&
+                                (search.location == null || user.location == search.location) &&
+                                (search.ageMin == null || user.age >= search.ageMin) &&
+                                (search.ageMax == null || user.age <= search.ageMax)
+                            }
+                            FriendsList(matchingUsers)
+                        }
+                    }
+                }
+            )
+        }
+    }
+}
diff --git a/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/NavRecipeKey.kt b/app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/NavRecipeKey.kt
