Merge pull request #859 from arkivanov/backHandlerPriority

Added backHandlerPriority argument to childContext extension function

Author: arkivanov

decompose/api/android/decompose.api

@@ -47,6 +47,8 @@ public abstract interface class com/arkivanov/decompose/ComponentContext : com/a
 
 public final class com/arkivanov/decompose/ComponentContextExtKt {
 	public static final fun childContext (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;)Lcom/arkivanov/decompose/GenericComponentContext;
+	public static final fun childContext (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;I)Lcom/arkivanov/decompose/GenericComponentContext;
+	public static synthetic fun childContext$default (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;IILjava/lang/Object;)Lcom/arkivanov/decompose/GenericComponentContext;
 	public static synthetic fun childContext$default (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;ILjava/lang/Object;)Lcom/arkivanov/decompose/GenericComponentContext;
 }
 

decompose/api/decompose.klib.api

@@ -495,6 +495,7 @@ final fun <#A: com.arkivanov.decompose/GenericComponentContext<#A>, #B: kotlin/A
 final fun <#A: com.arkivanov.decompose/GenericComponentContext<#A>, #B: kotlin/Any, #C: kotlin/Any> (#A).com.arkivanov.decompose.router.stack/childStack(com.arkivanov.decompose.router.children/NavigationSource<com.arkivanov.decompose.router.stack/StackNavigation.Event<#B>>, kotlinx.serialization/KSerializer<#B>?, #B, kotlin/String = ..., kotlin/Boolean = ..., kotlin/Function2<#B, #A, #C>): com.arkivanov.decompose.value/Value<com.arkivanov.decompose.router.stack/ChildStack<#B, #C>> // com.arkivanov.decompose.router.stack/childStack|childStack@0:0(com.arkivanov.decompose.router.children.NavigationSource<com.arkivanov.decompose.router.stack.StackNavigation.Event<0:1>>;kotlinx.serialization.KSerializer<0:1>?;0:1;kotlin.String;kotlin.Boolean;kotlin.Function2<0:1,0:0,0:2>){0§<com.arkivanov.decompose.GenericComponentContext<0:0>>;1§<kotlin.Any>;2§<kotlin.Any>}[0]
 final fun <#A: com.arkivanov.decompose/GenericComponentContext<#A>, #B: kotlin/Any, #C: kotlin/Any> (#A).com.arkivanov.decompose.router.stack/childStack(com.arkivanov.decompose.router.children/NavigationSource<com.arkivanov.decompose.router.stack/StackNavigation.Event<#B>>, kotlinx.serialization/KSerializer<#B>?, kotlin/Function0<kotlin.collections/List<#B>>, kotlin/String = ..., kotlin/Boolean = ..., kotlin/Function2<#B, #A, #C>): com.arkivanov.decompose.value/Value<com.arkivanov.decompose.router.stack/ChildStack<#B, #C>> // com.arkivanov.decompose.router.stack/childStack|childStack@0:0(com.arkivanov.decompose.router.children.NavigationSource<com.arkivanov.decompose.router.stack.StackNavigation.Event<0:1>>;kotlinx.serialization.KSerializer<0:1>?;kotlin.Function0<kotlin.collections.List<0:1>>;kotlin.String;kotlin.Boolean;kotlin.Function2<0:1,0:0,0:2>){0§<com.arkivanov.decompose.GenericComponentContext<0:0>>;1§<kotlin.Any>;2§<kotlin.Any>}[0]
 final fun <#A: com.arkivanov.decompose/GenericComponentContext<#A>> (#A).com.arkivanov.decompose/childContext(kotlin/String, com.arkivanov.essenty.lifecycle/Lifecycle? = ...): #A // com.arkivanov.decompose/childContext|childContext@0:0(kotlin.String;com.arkivanov.essenty.lifecycle.Lifecycle?){0§<com.arkivanov.decompose.GenericComponentContext<0:0>>}[0]
+final fun <#A: com.arkivanov.decompose/GenericComponentContext<#A>> (#A).com.arkivanov.decompose/childContext(kotlin/String, com.arkivanov.essenty.lifecycle/Lifecycle? = ..., kotlin/Int): #A // com.arkivanov.decompose/childContext|childContext@0:0(kotlin.String;com.arkivanov.essenty.lifecycle.Lifecycle?;kotlin.Int){0§<com.arkivanov.decompose.GenericComponentContext<0:0>>}[0]
 final fun <#A: kotlin/Any, #B: kotlin/Any, #C: kotlin/Any, #D: kotlin/Any, #E: kotlin/Any, #F: kotlin/Any> com.arkivanov.decompose.router.panels/childPanelsWebNavigation(com.arkivanov.decompose.router.panels/PanelsNavigator<#A, #C, #E>, com.arkivanov.decompose.value/Value<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, #E, #F>>, kotlin/Triple<kotlinx.serialization/KSerializer<#A>, kotlinx.serialization/KSerializer<#C>, kotlinx.serialization/KSerializer<#E>>, kotlin/Function1<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, #E, #F>, kotlin/String?> = ..., kotlin/Function1<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, #E, #F>, kotlin.collections/Map<kotlin/String, kotlin/String>?> = ..., kotlin/Function0<kotlin/Boolean> = ..., kotlin/Function1<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, #E, #F>, com.arkivanov.decompose.router.webhistory/WebNavigationOwner?> = ...): com.arkivanov.decompose.router.webhistory/WebNavigation<*> // com.arkivanov.decompose.router.panels/childPanelsWebNavigation|childPanelsWebNavigation(com.arkivanov.decompose.router.panels.PanelsNavigator<0:0,0:2,0:4>;com.arkivanov.decompose.value.Value<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,0:4,0:5>>;kotlin.Triple<kotlinx.serialization.KSerializer<0:0>,kotlinx.serialization.KSerializer<0:2>,kotlinx.serialization.KSerializer<0:4>>;kotlin.Function1<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,0:4,0:5>,kotlin.String?>;kotlin.Function1<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,0:4,0:5>,kotlin.collections.Map<kotlin.String,kotlin.String>?>;kotlin.Function0<kotlin.Boolean>;kotlin.Function1<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,0:4,0:5>,com.arkivanov.decompose.router.webhistory.WebNavigationOwner?>){0§<kotlin.Any>;1§<kotlin.Any>;2§<kotlin.Any>;3§<kotlin.Any>;4§<kotlin.Any>;5§<kotlin.Any>}[0]
 final fun <#A: kotlin/Any, #B: kotlin/Any, #C: kotlin/Any, #D: kotlin/Any> com.arkivanov.decompose.router.panels/childPanelsWebNavigation(com.arkivanov.decompose.router.panels/PanelsNavigator<#A, #C, kotlin/Nothing>, com.arkivanov.decompose.value/Value<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, kotlin/Nothing, kotlin/Nothing>>, kotlin/Pair<kotlinx.serialization/KSerializer<#A>, kotlinx.serialization/KSerializer<#C>>, kotlin/Function1<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, kotlin/Nothing, kotlin/Nothing>, kotlin/String?> = ..., kotlin/Function1<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, kotlin/Nothing, kotlin/Nothing>, kotlin.collections/Map<kotlin/String, kotlin/String>?> = ..., kotlin/Function0<kotlin/Boolean> = ..., kotlin/Function1<com.arkivanov.decompose.router.panels/ChildPanels<#A, #B, #C, #D, kotlin/Nothing, kotlin/Nothing>, com.arkivanov.decompose.router.webhistory/WebNavigationOwner?> = ...): com.arkivanov.decompose.router.webhistory/WebNavigation<*> // com.arkivanov.decompose.router.panels/childPanelsWebNavigation|childPanelsWebNavigation(com.arkivanov.decompose.router.panels.PanelsNavigator<0:0,0:2,kotlin.Nothing>;com.arkivanov.decompose.value.Value<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,kotlin.Nothing,kotlin.Nothing>>;kotlin.Pair<kotlinx.serialization.KSerializer<0:0>,kotlinx.serialization.KSerializer<0:2>>;kotlin.Function1<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,kotlin.Nothing,kotlin.Nothing>,kotlin.String?>;kotlin.Function1<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,kotlin.Nothing,kotlin.Nothing>,kotlin.collections.Map<kotlin.String,kotlin.String>?>;kotlin.Function0<kotlin.Boolean>;kotlin.Function1<com.arkivanov.decompose.router.panels.ChildPanels<0:0,0:1,0:2,0:3,kotlin.Nothing,kotlin.Nothing>,com.arkivanov.decompose.router.webhistory.WebNavigationOwner?>){0§<kotlin.Any>;1§<kotlin.Any>;2§<kotlin.Any>;3§<kotlin.Any>}[0]
 final fun <#A: kotlin/Any, #B: kotlin/Any, #C: kotlin/Any> (com.arkivanov.decompose.router.panels/PanelsNavigator<#A, #B, #C>).com.arkivanov.decompose.router.panels/activateDetails(#B, kotlin/Function2<com.arkivanov.decompose.router.panels/Panels<#A, #B, #C>, com.arkivanov.decompose.router.panels/Panels<#A, #B, #C>, kotlin/Unit> = ...) // com.arkivanov.decompose.router.panels/activateDetails|activateDetails@com.arkivanov.decompose.router.panels.PanelsNavigator<0:0,0:1,0:2>(0:1;kotlin.Function2<com.arkivanov.decompose.router.panels.Panels<0:0,0:1,0:2>,com.arkivanov.decompose.router.panels.Panels<0:0,0:1,0:2>,kotlin.Unit>){0§<kotlin.Any>;1§<kotlin.Any>;2§<kotlin.Any>}[0]

decompose/api/jvm/decompose.api

@@ -47,6 +47,8 @@ public abstract interface class com/arkivanov/decompose/ComponentContext : com/a
 
 public final class com/arkivanov/decompose/ComponentContextExtKt {
 	public static final fun childContext (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;)Lcom/arkivanov/decompose/GenericComponentContext;
+	public static final fun childContext (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;I)Lcom/arkivanov/decompose/GenericComponentContext;
+	public static synthetic fun childContext$default (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;IILjava/lang/Object;)Lcom/arkivanov/decompose/GenericComponentContext;
 	public static synthetic fun childContext$default (Lcom/arkivanov/decompose/GenericComponentContext;Ljava/lang/String;Lcom/arkivanov/essenty/lifecycle/Lifecycle;ILjava/lang/Object;)Lcom/arkivanov/decompose/GenericComponentContext;
 }
 

decompose/src/commonMain/kotlin/com/arkivanov/decompose/ComponentContextExt.kt

@@ -4,11 +4,13 @@ import com.arkivanov.decompose.backhandler.child
 import com.arkivanov.decompose.instancekeeper.child
 import com.arkivanov.decompose.lifecycle.MergedLifecycle
 import com.arkivanov.decompose.statekeeper.child
+import com.arkivanov.essenty.backhandler.BackCallback
 import com.arkivanov.essenty.lifecycle.Lifecycle
 import com.arkivanov.essenty.lifecycle.doOnDestroy
 
 /**
- * Creates a new instance of child component context of type [Ctx] and attaches it to the parent (`this`) component context.
+ * Creates a new instance of child [ComponentContext] of type [Ctx] and attaches it to the parent (`this`) component context.
+ * Can be used to create fixed child components (i.e. without navigation) living as long as the parent (hosting) component.
  *
  * @param key A key of the child component context, must be unique within the parent context.
  * @param lifecycle An optional [Lifecycle] of the child component context to be merged with the parent [Lifecycle],
@@ -17,13 +19,41 @@ import com.arkivanov.essenty.lifecycle.doOnDestroy
  * - The resulting [Lifecycle] of the child component will honour both the parent (`this`) [Lifecycle] and the supplied one.
  * - The supplied [Lifecycle] must never be destroyed manually.
  */
-fun <Ctx : GenericComponentContext<Ctx>> Ctx.childContext(key: String, lifecycle: Lifecycle? = null): Ctx {
+fun <Ctx : GenericComponentContext<Ctx>> Ctx.childContext(key: String, lifecycle: Lifecycle? = null): Ctx =
+    childContext(
+        key = key,
+        lifecycle = lifecycle,
+        backHandlerPriority = BackCallback.PRIORITY_DEFAULT,
+    )
+
+/**
+ * Creates a new instance of child [ComponentContext] of type [Ctx] and attaches it to the parent (`this`) component context.
+ * Can be used to create fixed child components (i.e. without navigation) living as long as the parent (hosting) component.
+ *
+ * @param key A key of the child component context, must be unique within the parent context.
+ * @param lifecycle An optional [Lifecycle] of the child component context to be merged with the parent [Lifecycle],
+ * can be used for manual control (see [LifecycleRegistry][com.arkivanov.essenty.lifecycle.LifecycleRegistry]).
+ * The following conditions apply:
+ * - The resulting [Lifecycle] of the child component will honour both the parent (`this`) [Lifecycle] and the supplied one.
+ * - The supplied [Lifecycle] must never be destroyed manually.
+ * @param backHandlerPriority a priority of the `BackHandler` used by the returned [ComponentContext] in the scope of the
+ * parent (`this`) [ComponentContext]. By default, back handlers of the child component contexts and normal `BackCallbacks`
+ * registered in the parent (hosting) component context's `BackHandler` handle the back button in the reverse order.
+ * E.g. with two child component contexts, the second one handles the back button before the first one.
+ * The [backHandlerPriority] parameter allows to explicitly control the order.
+ */
+@ExperimentalDecomposeApi
+fun <Ctx : GenericComponentContext<Ctx>> Ctx.childContext(
+    key: String,
+    lifecycle: Lifecycle? = null,
+    backHandlerPriority: Int,
+): Ctx {
     lifecycle?.doOnDestroy { error("The lifecycle of a child ComponentContext must never be destroyed manually.") }
 
     return componentContextFactory(
         lifecycle = if (lifecycle == null) this.lifecycle else MergedLifecycle(this.lifecycle, lifecycle),
         stateKeeper = stateKeeper.child(key, lifecycle),
         instanceKeeper = instanceKeeper.child(key, lifecycle),
-        backHandler = backHandler.child(lifecycle),
+        backHandler = backHandler.child(lifecycle, backHandlerPriority),
     )
 }

decompose/src/commonTest/kotlin/com/arkivanov/decompose/ChildContextWithBackHandlerPriorityTest.kt

@@ -0,0 +1,88 @@
+package com.arkivanov.decompose
+
+import com.arkivanov.decompose.statekeeper.TestStateKeeperDispatcher
+import com.arkivanov.essenty.backhandler.BackCallback
+import com.arkivanov.essenty.backhandler.BackDispatcher
+import com.arkivanov.essenty.instancekeeper.InstanceKeeperDispatcher
+import com.arkivanov.essenty.lifecycle.LifecycleRegistry
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+@Suppress("TestFunctionName")
+class ChildContextWithBackHandlerPriorityTest {
+
+    @Test
+    fun GIVEN_backHandlerPriority_specified_WHEN_back_THEN_order_according_to_priority() {
+        val backDispatcher = BackDispatcher()
+        val context = TestContext(backDispatcher)
+        val childContext1 = context.childContext(key = "context1", backHandlerPriority = 3)
+        val childContext2 = context.childContext(key = "context2", backHandlerPriority = 4)
+        val childContext3 = context.childContext(key = "context3", backHandlerPriority = 2)
+        val events = ArrayList<String>()
+        val backCallback01 = BackCallback(priority = 1) { events += "01" }
+        val backCallback02 = BackCallback(priority = 5) { events += "02" }
+        val backCallback1 = BackCallback { events += "1" }
+        val backCallback2 = BackCallback { events += "2" }
+        val backCallback3 = BackCallback { events += "3" }
+        context.backHandler.register(backCallback01)
+        context.backHandler.register(backCallback02)
+        childContext1.backHandler.register(backCallback1)
+        childContext2.backHandler.register(backCallback2)
+        childContext3.backHandler.register(backCallback3)
+
+        backDispatcher.back()
+        backCallback02.isEnabled = false
+        backDispatcher.back()
+        backCallback2.isEnabled = false
+        backDispatcher.back()
+        backCallback1.isEnabled = false
+        backDispatcher.back()
+        backCallback3.isEnabled = false
+        backDispatcher.back()
+
+        assertEquals(listOf("02", "2", "1", "3", "01"), events)
+    }
+
+    @Test
+    fun GIVEN_backHandlerPriority_not_specified_WHEN_back_THEN_reverse_order() {
+        val backDispatcher = BackDispatcher()
+        val context = TestContext(backDispatcher)
+        val childContext1 = context.childContext(key = "context1")
+        val childContext2 = context.childContext(key = "context2")
+        val childContext3 = context.childContext(key = "context3")
+        val events = ArrayList<String>()
+        val backCallback01 = BackCallback { events += "01" }
+        val backCallback02 = BackCallback { events += "02" }
+        val backCallback1 = BackCallback { events += "1" }
+        val backCallback2 = BackCallback { events += "2" }
+        val backCallback3 = BackCallback { events += "3" }
+        context.backHandler.register(backCallback01)
+        context.backHandler.register(backCallback02)
+        childContext1.backHandler.register(backCallback1)
+        childContext2.backHandler.register(backCallback2)
+        childContext3.backHandler.register(backCallback3)
+
+        backDispatcher.back()
+        backCallback02.isEnabled = false
+        backDispatcher.back()
+        backCallback01.isEnabled = false
+        backDispatcher.back()
+        backCallback3.isEnabled = false
+        backDispatcher.back()
+        backCallback2.isEnabled = false
+        backDispatcher.back()
+        backCallback1.isEnabled = false
+        backDispatcher.back()
+
+        assertEquals(listOf("02", "01", "3", "2", "1"), events)
+    }
+
+    private class TestContext(
+        override val backHandler: BackDispatcher = BackDispatcher()
+    ) : ComponentContext {
+        override val lifecycle: LifecycleRegistry = LifecycleRegistry()
+        override val stateKeeper: TestStateKeeperDispatcher = TestStateKeeperDispatcher()
+        override val instanceKeeper: InstanceKeeperDispatcher = InstanceKeeperDispatcher()
+        override val componentContextFactory: ComponentContextFactory<ComponentContext> = ComponentContextFactory(::DefaultComponentContext)
+    }
+}