Added handleDeepLink function with additional parameters

decompose/api/android/decompose.api

@@ -93,7 +93,9 @@ public final class com/arkivanov/decompose/DecomposeSettings$Companion {
 }
 
 public final class com/arkivanov/decompose/DeeplinkUtilsKt {
+	public static final fun handleDeepLink (Landroid/app/Activity;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static final fun handleDeepLink (Landroid/app/Activity;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
+	public static synthetic fun handleDeepLink$default (Landroid/app/Activity;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ljava/lang/Object;
 }
 
 public final class com/arkivanov/decompose/DefaultComponentContext : com/arkivanov/decompose/ComponentContext {
@@ -128,6 +130,11 @@ public abstract interface annotation class com/arkivanov/decompose/FaultyDecompo
 public abstract interface class com/arkivanov/decompose/GenericComponentContext : com/arkivanov/decompose/ComponentContextFactoryOwner, com/arkivanov/essenty/backhandler/BackHandlerOwner, com/arkivanov/essenty/instancekeeper/InstanceKeeperOwner, com/arkivanov/essenty/lifecycle/LifecycleOwner, com/arkivanov/essenty/statekeeper/StateKeeperOwner {
 }
 
+public final class com/arkivanov/decompose/HandleDeepLinkDefaults {
+	public static final field INSTANCE Lcom/arkivanov/decompose/HandleDeepLinkDefaults;
+	public final fun shouldRestartInNewTask (Landroid/app/Activity;)Z
+}
+
 public abstract interface annotation class com/arkivanov/decompose/InternalDecomposeApi : java/lang/annotation/Annotation {
 }
 

decompose/src/androidMain/kotlin/com/arkivanov/decompose/DeeplinkUtils.kt

@@ -2,7 +2,8 @@ package com.arkivanov.decompose
 
 import android.app.Activity
 import android.app.TaskStackBuilder
-import android.content.Intent
+import android.content.Intent.FLAG_ACTIVITY_CLEAR_TASK
+import android.content.Intent.FLAG_ACTIVITY_NEW_TASK
 import android.net.Uri
 import android.os.Build
 import android.os.Bundle
@@ -12,16 +13,20 @@ import androidx.core.os.bundleOf
 import androidx.savedstate.SavedStateRegistryOwner
 
 /**
- * Extracts a deep link URL from this [Activity] [Intent], calls [block]
- * function with the extracted deep link URL (if any) and returns the result.
+ * Extracts a deep link URL from this [Activity.intent], calls [block]
+ * function with the extracted deep link [Uri] (if any) and returns the result.
+ *
+ * Also restarts this `Activity` with [FLAG_ACTIVITY_CLEAR_TASK] if there is
+ * a deep link and the [Activity.intent] has the [FLAG_ACTIVITY_NEW_TASK] flag set
+ * and the [FLAG_ACTIVITY_CLEAR_TASK] flag is not set.
+ * Returns `null` if this `Activity` restart has been initiated.
  *
  * This function must be called from [Activity.onCreate] method.
  *
- * It is strongly recommended to always use the `standard` (default)
+ * It is [strongly recommended](https://developer.android.com/guide/navigation/design/deep-link#handle)
+ * to always use the `standard` (default)
  * [launchMode](https://developer.android.com/guide/components/activities/tasks-and-back-stack#TaskLaunchModes)
- * for the [Activity] when handling deep links. This function takes care of
- * restarting the [Activity] task and finishing this [Activity] if needed,
- * in which case the returned value is `null`.
+ * for the [Activity] when handling deep links.
  *
  * Example of creating a root component with deep link support.
  *
@@ -37,7 +42,7 @@ import androidx.savedstate.SavedStateRegistryOwner
  *                     componentContext = defaultComponentContext(discardSavedState = itemId != null),
  *                     itemId = itemId,
  *                 )
- *             } ?: return
+ *             } ?: return // Return if the Activity restart has been initiated
  *
  *         // Display the root component as usual
  *     }
@@ -50,35 +55,95 @@ import androidx.savedstate.SavedStateRegistryOwner
 @ExperimentalDecomposeApi
 fun <A, T : Any> A.handleDeepLink(
     block: (Uri?) -> T,
-): T? where A : Activity, A : SavedStateRegistryOwner {
-    val intentData: Uri? = intent.data
+): T? where A : Activity, A : SavedStateRegistryOwner =
+    handleDeepLink(
+        deepLink = intent.data,
+        block = block,
+    )
 
-    if ((intentData != null) && restartIfNeeded()) {
+/**
+ * Calls the provided [block] function with the given [deepLink] if this is the first launch of
+ * this [Activity] (e.g. not a configuration change or restoration after process death),
+ * and returns the result.
+ *
+ * Also restarts this `Activity` with [FLAG_ACTIVITY_CLEAR_TASK] if the provided [deepLink]
+ * is not `null` and [shouldRestartInNewTask] predicate returned `true`. By default,
+ * [shouldRestartInNewTask] returns `true` if the [Activity.intent] has the
+ * [FLAG_ACTIVITY_NEW_TASK] flag set and the [FLAG_ACTIVITY_CLEAR_TASK] flag is not set.
+ * Returns `null` if this `Activity` restart has been initiated.
+ *
+ * This function must be called from [Activity.onCreate] method.
+ *
+ * It is [strongly recommended](https://developer.android.com/guide/navigation/design/deep-link#handle)
+ * to always use the `standard` (default)
+ * [launchMode](https://developer.android.com/guide/components/activities/tasks-and-back-stack#TaskLaunchModes)
+ * for the [Activity] when handling deep links.
+ *
+ * Example of creating a root component with deep link support.
+ *
+ * ```kotlin
+ * class MainActivity : AppCompatActivity() {
+ *     override fun onCreate(savedInstanceState: Bundle?) {
+ *         super.onCreate(savedInstanceState)
+ *
+ *         val root =
+ *             handleDeepLink(deepLink = { intent.data?.extractItemId() }) { itemId ->
+ *                 DefaultRootComponent(
+ *                     componentContext = defaultComponentContext(discardSavedState = itemId != null),
+ *                     itemId = itemId,
+ *                 )
+ *             } ?: return // Return if the Activity restart has been initiated
+ *
+ *         // Display the root component as usual
+ *     }
+ *
+ *     private fun Uri.extractItemId(): String? =
+ *         TODO("Extract item id from the deep link")
+ * }
+ * ```
+ */
+@ExperimentalDecomposeApi
+fun <A, D : Any, T : Any> A.handleDeepLink(
+    deepLink: D?,
+    shouldRestartInNewTask: (D) -> Boolean = { HandleDeepLinkDefaults.shouldRestartInNewTask(this) },
+    block: (D?) -> T,
+): T? where A : Activity, A : SavedStateRegistryOwner {
+    if ((deepLink != null) && shouldRestartInNewTask(deepLink)) {
+        restart()
         return null
     }
 
     val savedState: Bundle? = savedStateRegistry.consumeRestoredStateForKey(key = KEY_SAVED_DEEP_LINK_STATE)
     val isDeepLinkHandled = savedState?.getBoolean(KEY_DEEP_LINK_HANDLED) ?: false
-    val deepLink = intentData?.takeUnless { isDeepLinkHandled }
 
     savedStateRegistry.registerSavedStateProvider(key = KEY_SAVED_DEEP_LINK_STATE) {
         bundleOf(KEY_DEEP_LINK_HANDLED to (isDeepLinkHandled || (deepLink != null)))
     }
 
-    return block(deepLink)
+    return block(deepLink?.takeUnless { isDeepLinkHandled })
 }
 
-// Derived from https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:navigation/navigation-runtime/src/main/java/androidx/navigation/NavController.kt;l=1486;drc=fd7d0dc4a56c2aef65424db7986aa057f9717661
-private fun Activity.restartIfNeeded(): Boolean {
-    if ((intent.flags and Intent.FLAG_ACTIVITY_NEW_TASK == 0) || (intent.flags and Intent.FLAG_ACTIVITY_CLEAR_TASK != 0)) {
-        return false
-    }
+@ExperimentalDecomposeApi
+object HandleDeepLinkDefaults {
+
+    /**
+     * Checks if the provided [activity] should be restarted for deep link handling.
+     *
+     * @return `true` if the [Activity.intent] has the [FLAG_ACTIVITY_NEW_TASK] flag set and
+     * the [FLAG_ACTIVITY_CLEAR_TASK] flag is not set, `false` otherwise.
+     */
+    fun shouldRestartInNewTask(activity: Activity): Boolean =
+        (activity.intent.flags and FLAG_ACTIVITY_NEW_TASK != 0) &&
+            (activity.intent.flags and FLAG_ACTIVITY_CLEAR_TASK == 0)
+}
 
+// Derived from https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:navigation/navigation-runtime/src/main/java/androidx/navigation/NavController.kt;l=1486;drc=fd7d0dc4a56c2aef65424db7986aa057f9717661
+private fun Activity.restart() {
     // Someone called us with NEW_TASK, but we don't know what state our whole
     // task stack is in, so we need to manually restart the whole stack to
     // ensure we're in a predictably good state.
 
-    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK)
+    intent.addFlags(FLAG_ACTIVITY_CLEAR_TASK)
 
     withPermittedUnsafeIntentLaunch {
         TaskStackBuilder.create(this).addNextIntentWithParentStack(intent).startActivities()
@@ -89,8 +154,6 @@ private fun Activity.restartIfNeeded(): Boolean {
     // Disable second animation in case where the Activity is created twice.
     @Suppress("DEPRECATION")
     overridePendingTransition(0, 0)
-
-    return true
 }
 
 private inline fun withPermittedUnsafeIntentLaunch(block: () -> Unit) {