Added StackNavigator#popToFirst extension function

decompose/api/android/decompose.api

@@ -317,6 +317,8 @@ public final class com/arkivanov/decompose/router/stack/StackNavigatorExtKt {
 	public static synthetic fun pop$default (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public static final fun popTo (Lcom/arkivanov/decompose/router/stack/StackNavigator;ILkotlin/jvm/functions/Function1;)V
 	public static synthetic fun popTo$default (Lcom/arkivanov/decompose/router/stack/StackNavigator;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
+	public static final fun popToFirst (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;)V
+	public static synthetic fun popToFirst$default (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public static final fun popWhile (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;)V
 	public static final fun popWhile (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
 	public static final fun push (Lcom/arkivanov/decompose/router/stack/StackNavigator;Ljava/lang/Object;Lkotlin/jvm/functions/Function0;)V

decompose/api/decompose.klib.api

@@ -167,12 +167,6 @@ final class <#A: out kotlin/Any> com.arkivanov.decompose.router.pages/Pages { //
     final val selectedIndex // com.arkivanov.decompose.router.pages/Pages.selectedIndex|{}selectedIndex[0]
         final fun <get-selectedIndex>(): kotlin/Int // com.arkivanov.decompose.router.pages/Pages.selectedIndex.<get-selectedIndex>|<get-selectedIndex>(){}[0]
 }
-final class com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController : com.arkivanov.decompose.router.stack.webhistory/WebHistoryController { // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController|null[0]
-    constructor <init>() // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.<init>|<init>(){}[0]
-    final fun <#A1: kotlin/Any> attach(com.arkivanov.decompose.router.stack/StackNavigator<#A1>, com.arkivanov.decompose.value/Value<com.arkivanov.decompose.router.stack/ChildStack<#A1, *>>, kotlinx.serialization/KSerializer<#A1>, kotlin/Function1<#A1, kotlin/String>, kotlin/Function1<kotlin/String, #A1>, kotlin/Function1<kotlin.collections/List<#A1>, kotlin/Boolean>) // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.attach|attach(com.arkivanov.decompose.router.stack.StackNavigator<0:0>;com.arkivanov.decompose.value.Value<com.arkivanov.decompose.router.stack.ChildStack<0:0,*>>;kotlinx.serialization.KSerializer<0:0>;kotlin.Function1<0:0,kotlin.String>;kotlin.Function1<kotlin.String,0:0>;kotlin.Function1<kotlin.collections.List<0:0>,kotlin.Boolean>){0§<kotlin.Any>}[0]
-    final val historyPaths // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.historyPaths|{}historyPaths[0]
-        final fun <get-historyPaths>(): kotlin.collections/List<kotlin/String> // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.historyPaths.<get-historyPaths>|<get-historyPaths>(){}[0]
-}
 final class com.arkivanov.decompose/DefaultComponentContext : com.arkivanov.decompose/ComponentContext { // com.arkivanov.decompose/DefaultComponentContext|null[0]
     constructor <init>(com.arkivanov.essenty.lifecycle/Lifecycle) // com.arkivanov.decompose/DefaultComponentContext.<init>|<init>(com.arkivanov.essenty.lifecycle.Lifecycle){}[0]
     constructor <init>(com.arkivanov.essenty.lifecycle/Lifecycle, com.arkivanov.essenty.statekeeper/StateKeeper? = ..., com.arkivanov.essenty.instancekeeper/InstanceKeeper? = ..., com.arkivanov.essenty.backhandler/BackHandler? = ...) // com.arkivanov.decompose/DefaultComponentContext.<init>|<init>(com.arkivanov.essenty.lifecycle.Lifecycle;com.arkivanov.essenty.statekeeper.StateKeeper?;com.arkivanov.essenty.instancekeeper.InstanceKeeper?;com.arkivanov.essenty.backhandler.BackHandler?){}[0]
@@ -227,6 +221,7 @@ final fun <#A: kotlin/Any> com.arkivanov.decompose.router.stack/StackNavigation(
 final fun <#A: kotlin/Any> com.arkivanov.decompose.value/MutableValue(#A): com.arkivanov.decompose.value/MutableValue<#A> // com.arkivanov.decompose.value/MutableValue|MutableValue(0:0){0§<kotlin.Any>}[0]
 final fun com.arkivanov.decompose.router.pages/getDefaultPageStatus(kotlin/Int, com.arkivanov.decompose.router.pages/Pages<*>): com.arkivanov.decompose.router.children/ChildNavState.Status // com.arkivanov.decompose.router.pages/getDefaultPageStatus|getDefaultPageStatus(kotlin.Int;com.arkivanov.decompose.router.pages.Pages<*>){}[0]
 final inline fun (com.arkivanov.decompose.router.slot/SlotNavigator<*>).com.arkivanov.decompose.router.slot/dismiss(crossinline kotlin/Function1<kotlin/Boolean, kotlin/Unit> = ...) // com.arkivanov.decompose.router.slot/dismiss|dismiss@com.arkivanov.decompose.router.slot.SlotNavigator<*>(kotlin.Function1<kotlin.Boolean,kotlin.Unit>){}[0]
+final inline fun (com.arkivanov.decompose.router.stack/StackNavigator<*>).com.arkivanov.decompose.router.stack/popToFirst(crossinline kotlin/Function1<kotlin/Boolean, kotlin/Unit> = ...) // com.arkivanov.decompose.router.stack/popToFirst|popToFirst@com.arkivanov.decompose.router.stack.StackNavigator<*>(kotlin.Function1<kotlin.Boolean,kotlin.Unit>){}[0]
 final inline fun <#A: kotlin/Any> (com.arkivanov.decompose.router.slot/SlotNavigator<#A>).com.arkivanov.decompose.router.slot/activate(#A, crossinline kotlin/Function0<kotlin/Unit> = ...) // com.arkivanov.decompose.router.slot/activate|activate@com.arkivanov.decompose.router.slot.SlotNavigator<0:0>(0:0;kotlin.Function0<kotlin.Unit>){0§<kotlin.Any>}[0]
 final inline fun <#A: kotlin/Any> (com.arkivanov.decompose.router.stack/StackNavigator<#A>).com.arkivanov.decompose.router.stack/bringToFront(#A, crossinline kotlin/Function0<kotlin/Unit> = ...) // com.arkivanov.decompose.router.stack/bringToFront|bringToFront@com.arkivanov.decompose.router.stack.StackNavigator<0:0>(0:0;kotlin.Function0<kotlin.Unit>){0§<kotlin.Any>}[0]
 final inline fun <#A: kotlin/Any> (com.arkivanov.decompose.router.stack/StackNavigator<#A>).com.arkivanov.decompose.router.stack/pop(crossinline kotlin/Function1<kotlin/Boolean, kotlin/Unit> = ...) // com.arkivanov.decompose.router.stack/pop|pop@com.arkivanov.decompose.router.stack.StackNavigator<0:0>(kotlin.Function1<kotlin.Boolean,kotlin.Unit>){0§<kotlin.Any>}[0]
@@ -290,3 +285,10 @@ sealed class <#A: out kotlin/Any, #B: out kotlin/Any> com.arkivanov.decompose/Ch
             final fun <get-instance>(): kotlin/Nothing? // com.arkivanov.decompose/Child.Destroyed.instance.<get-instance>|<get-instance>(){}[0]
     }
 }
+// Targets: [js, wasmJs]
+final class com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController : com.arkivanov.decompose.router.stack.webhistory/WebHistoryController { // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController|null[0]
+    constructor <init>() // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.<init>|<init>(){}[0]
+    final fun <#A1: kotlin/Any> attach(com.arkivanov.decompose.router.stack/StackNavigator<#A1>, com.arkivanov.decompose.value/Value<com.arkivanov.decompose.router.stack/ChildStack<#A1, *>>, kotlinx.serialization/KSerializer<#A1>, kotlin/Function1<#A1, kotlin/String>, kotlin/Function1<kotlin/String, #A1>, kotlin/Function1<kotlin.collections/List<#A1>, kotlin/Boolean>) // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.attach|attach(com.arkivanov.decompose.router.stack.StackNavigator<0:0>;com.arkivanov.decompose.value.Value<com.arkivanov.decompose.router.stack.ChildStack<0:0,*>>;kotlinx.serialization.KSerializer<0:0>;kotlin.Function1<0:0,kotlin.String>;kotlin.Function1<kotlin.String,0:0>;kotlin.Function1<kotlin.collections.List<0:0>,kotlin.Boolean>){0§<kotlin.Any>}[0]
+    final val historyPaths // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.historyPaths|{}historyPaths[0]
+        final fun <get-historyPaths>(): kotlin.collections/List<kotlin/String> // com.arkivanov.decompose.router.stack.webhistory/DefaultWebHistoryController.historyPaths.<get-historyPaths>|<get-historyPaths>(){}[0]
+}

decompose/api/jvm/decompose.api

@@ -297,6 +297,8 @@ public final class com/arkivanov/decompose/router/stack/StackNavigatorExtKt {
 	public static synthetic fun pop$default (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public static final fun popTo (Lcom/arkivanov/decompose/router/stack/StackNavigator;ILkotlin/jvm/functions/Function1;)V
 	public static synthetic fun popTo$default (Lcom/arkivanov/decompose/router/stack/StackNavigator;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
+	public static final fun popToFirst (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;)V
+	public static synthetic fun popToFirst$default (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public static final fun popWhile (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;)V
 	public static final fun popWhile (Lcom/arkivanov/decompose/router/stack/StackNavigator;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
 	public static final fun push (Lcom/arkivanov/decompose/router/stack/StackNavigator;Ljava/lang/Object;Lkotlin/jvm/functions/Function0;)V

decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/StackNavigatorExt.kt

@@ -75,7 +75,7 @@ inline fun <C : Any> StackNavigator<C>.pop(crossinline onComplete: (isSuccess: B
 }
 
 /**
- * Drops the configurations at the top of the stack while the [predicate] returns `true`.
+ * Pops configurations at the top of the stack while the [predicate] returns `true`.
  * If the [predicate] returns `true` for every configuration, then the first (oldest) configuration
  * remains in the stack.
  */
@@ -84,7 +84,7 @@ inline fun <C : Any> StackNavigator<C>.popWhile(crossinline predicate: (C) -> Bo
 }
 
 /**
- * Drops the configurations at the top of the stack while the [predicate] returns true.
+ * Pops configurations at the top of the stack while the [predicate] returns true.
  * If the [predicate] returns `true` for every configuration, then the first (oldest) configuration
  * remains in the stack.
  *
@@ -102,7 +102,7 @@ inline fun <C : Any> StackNavigator<C>.popWhile(
 }
 
 /**
- * Drops configurations at the top of the stack so that the provided index becomes active (the new top of the stack).
+ * Pops configurations at the top of the stack so that the provided index becomes active (the new top of the stack).
  *
  * @param index the index of the configuration to become active. Must not be negative.
  * @param onComplete called when the navigation is finished (either synchronously or asynchronously).
@@ -120,6 +120,19 @@ inline fun <C : Any> StackNavigator<C>.popTo(
     )
 }
 
+/**
+ * Pops configurations at the top of the stack so that the first configuration becomes active (the new top of the stack).
+ * Does nothing if there is only one component in the stack.
+ *
+ * Equivalent to `popTo(index = 0)`.
+ *
+ * @param onComplete called when the navigation is finished (either synchronously or asynchronously).
+ * The `isSuccess` argument is `true` if at least one component has been popped.
+ */
+inline fun StackNavigator<*>.popToFirst(crossinline onComplete: (isSuccess: Boolean) -> Unit = {}) {
+    popTo(index = 0, onComplete = onComplete)
+}
+
 /**
  * Replaces the current configuration at the top of the stack with the provided [configuration].
  *

decompose/src/commonTest/kotlin/com/arkivanov/decompose/router/stack/RouterPopToFirstTest.kt

@@ -0,0 +1,72 @@
+package com.arkivanov.decompose.router.stack
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+@Suppress("TestFunctionName")
+class RouterPopToFirstTest {
+
+    @Test
+    fun GIVEN_stack_size_3_WHEN_popToFirst_THEN_popped() {
+        val navigator = TestStackNavigator(listOf(Config.A, Config.B, Config.C))
+
+        navigator.popToFirst()
+
+        assertEquals(listOf(Config.A), navigator.configurations)
+    }
+
+    @Test
+    fun GIVEN_stack_size_3_WHEN_popToFirst_THEN_onComplete_success() {
+        val navigator = TestStackNavigator(listOf(Config.A, Config.B, Config.C))
+        var isSuccess = false
+
+        navigator.popToFirst { isSuccess = it }
+
+        assertTrue(isSuccess)
+    }
+
+    @Test
+    fun GIVEN_stack_size_2_WHEN_popToFirst_THEN_popped() {
+        val navigator = TestStackNavigator(listOf(Config.A, Config.B))
+
+        navigator.popToFirst()
+
+        assertEquals(listOf(Config.A), navigator.configurations)
+    }
+
+    @Test
+    fun GIVEN_stack_size_2_WHEN_popToFirst_THEN_onComplete_success() {
+        val navigator = TestStackNavigator(listOf(Config.A, Config.B))
+        var isSuccess = false
+
+        navigator.popToFirst { isSuccess = it }
+
+        assertTrue(isSuccess)
+    }
+
+    @Test
+    fun GIVEN_stack_size_1_WHEN_popToFirst_THEN_not_popped() {
+        val navigator = TestStackNavigator(listOf(Config.A))
+
+        navigator.popToFirst()
+
+        assertEquals(listOf(Config.A), navigator.configurations)
+    }
+
+    @Test
+    fun GIVEN_stack_size_1_WHEN_popToFirst_THEN_onComplete_not_success() {
+        val navigator = TestStackNavigator(listOf(Config.A))
+        var isSuccess: Boolean? = null
+
+        navigator.popToFirst { isSuccess = it }
+
+        assertEquals(false, isSuccess)
+    }
+
+    private sealed class Config {
+        data object A : Config()
+        data object B : Config()
+        data object C : Config()
+    }
+}

decompose/src/commonTest/kotlin/com/arkivanov/decompose/router/stack/RouterPopToTest.kt

@@ -116,7 +116,7 @@ class RouterPopToTest {
         val navigator = TestStackNavigator(listOf(Config.A))
         var isSuccess: Boolean? = null
 
-        navigator.pop { isSuccess = it }
+        navigator.popTo(index = 0) { isSuccess = it }
 
         assertEquals(false, isSuccess)
     }