Annotate StackNavigator#push as delicate API

arkivanov · Jul 29, 2024 · 82f85be · 82f85be
1 parent 4cb68bc
commit 82f85be
Show file tree

Hide file tree

Showing 6 changed files with 21 additions and 8 deletions.
diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/Annotations.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/Annotations.kt
@@ -22,3 +22,11 @@ annotation class ExperimentalDecomposeApi
 @RequiresOptIn(level = RequiresOptIn.Level.WARNING)
 @Retention(AnnotationRetention.BINARY)
 annotation class FaultyDecomposeApi
+
+/**
+ * Marks delicate Decompose API that requires special attention when used.
+ * See the docs of the annotated API for more information.
+ */
+@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
+@Retention(AnnotationRetention.BINARY)
+annotation class DelicateDecomposeApi
diff --git a/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/StackNavigatorExt.kt b/decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/stack/StackNavigatorExt.kt
@@ -1,5 +1,7 @@
 package com.arkivanov.decompose.router.stack
 
+import com.arkivanov.decompose.DelicateDecomposeApi
+
 /**
  * A convenience method for [StackNavigator.navigate].
  */
@@ -11,12 +13,15 @@ fun <C : Any> StackNavigator<C>.navigate(transformer: (stack: List<C>) -> List<C
  * Pushes the provided [configuration] at the top of the stack.
  *
  * Decompose will throw an exception if the provided [configuration] is already present in the stack.
+ * This usually happens when a component is pushed on user interaction (e.g. a button click).
+ * Consider using [pushNew] instead.
  * You can also try enabling the experimental
  * [Duplicate Configurations][com.arkivanov.decompose.DecomposeExperimentFlags.duplicateConfigurationsEnabled] feature
- * to avoid the error.
+ * to avoid the error. But still, pushing duplicated components on top of the stack might be wrong.
  *
  * @param onComplete called when the navigation is finished (either synchronously or asynchronously).
  */
+@DelicateDecomposeApi
 inline fun <C : Any> StackNavigator<C>.push(configuration: C, crossinline onComplete: () -> Unit = {}) {
     navigate(transformer = { it + configuration }, onComplete = { _, _ -> onComplete() })
 }

diff --git a/docs/navigation/stack/navigation.md b/docs/navigation/stack/navigation.md
@@ -30,7 +30,7 @@ There are `StackNavigator` [extension functions](https://github.com/arkivanov/De
 
 ### push(configuration)
 
-Pushes the provided `Configuration` at the top of the stack. Decompose will throw an exception if the provided `Configuration` is already present in the stack.
+Pushes the provided `Configuration` at the top of the stack. Decompose will throw an exception if the provided `Configuration` is already present in the stack. This usually happens when a component is pushed on user interaction (e.g. a button click). Consider using [pushNew](#pushnewconfiguration) instead.
 
 !!! note "Illustration"
 

diff --git a/...d/shared/src/commonMain/kotlin/com/arkivanov/sample/shared/cards/DefaultCardsComponent.kt b/...d/shared/src/commonMain/kotlin/com/arkivanov/sample/shared/cards/DefaultCardsComponent.kt
@@ -7,7 +7,7 @@ import com.arkivanov.decompose.router.stack.childStack
 import com.arkivanov.decompose.router.stack.items
 import com.arkivanov.decompose.router.stack.navigate
 import com.arkivanov.decompose.router.stack.pop
-import com.arkivanov.decompose.router.stack.push
+import com.arkivanov.decompose.router.stack.pushNew
 import com.arkivanov.decompose.value.Value
 import com.arkivanov.sample.shared.cards.card.CardComponent
 import com.arkivanov.sample.shared.cards.card.DefaultCardComponent
@@ -54,7 +54,7 @@ class DefaultCardsComponent(
 
         val maxNumber = _stack.items.maxOf { it.configuration.number }
 
-        navigation.push(
+        navigation.pushNew(
             Config(
                 color = COLORS[maxNumber % COLORS.size],
                 number = maxNumber + 1,

diff --git a/...ed/src/commonMain/kotlin/com/arkivanov/sample/shared/counters/DefaultCountersComponent.kt b/...ed/src/commonMain/kotlin/com/arkivanov/sample/shared/counters/DefaultCountersComponent.kt
@@ -6,7 +6,7 @@ import com.arkivanov.decompose.router.stack.StackNavigation
 import com.arkivanov.decompose.router.stack.childStack
 import com.arkivanov.decompose.router.stack.pop
 import com.arkivanov.decompose.router.stack.popTo
-import com.arkivanov.decompose.router.stack.push
+import com.arkivanov.decompose.router.stack.pushNew
 import com.arkivanov.decompose.value.Value
 import com.arkivanov.sample.shared.counters.counter.CounterComponent
 import com.arkivanov.sample.shared.counters.counter.DefaultCounterComponent
@@ -36,7 +36,7 @@ internal class DefaultCountersComponent(
             componentContext = componentContext,
             title = "Counter ${config.index}",
             isBackEnabled = config.isBackEnabled,
-            onNext = { navigation.push(Config(index = config.index + 1, isBackEnabled = true)) },
+            onNext = { navigation.pushNew(Config(index = config.index + 1, isBackEnabled = true)) },
             onPrev = navigation::pop,
         )
 

diff --git a/...ain/kotlin/com/arkivanov/sample/shared/dynamicfeatures/DefaultDynamicFeaturesComponent.kt b/...ain/kotlin/com/arkivanov/sample/shared/dynamicfeatures/DefaultDynamicFeaturesComponent.kt
@@ -5,7 +5,7 @@ import com.arkivanov.decompose.router.stack.ChildStack
 import com.arkivanov.decompose.router.stack.StackNavigation
 import com.arkivanov.decompose.router.stack.childStack
 import com.arkivanov.decompose.router.stack.pop
-import com.arkivanov.decompose.router.stack.push
+import com.arkivanov.decompose.router.stack.pushNew
 import com.arkivanov.decompose.value.Value
 import com.arkivanov.sample.shared.dynamicfeatures.DynamicFeaturesComponent.Child
 import com.arkivanov.sample.shared.dynamicfeatures.DynamicFeaturesComponent.Child.Feature1Child
@@ -51,7 +51,7 @@ internal class DefaultDynamicFeaturesComponent(
             factory = { featureComponentContext ->
                 Feature1(
                     componentContext = featureComponentContext,
-                    onFeature2 = { navigation.push(Config.Feature2(magicNumber = Random.nextInt())) },
+                    onFeature2 = { navigation.pushNew(Config.Feature2(magicNumber = Random.nextInt())) },
                 )
             }
         )