Merge branch 'master' into compose-experimental

README.md

@@ -20,7 +20,7 @@
 
 ---
 
-Decompose is a Kotlin Multiplatform library for breaking down your code into tree-structured lifecycle-aware business logic components (aka BLoC), with routing functionality and pluggable UI (Jetpack Compose, Android Views, SwiftUI, JS React, etc.).
+Decompose is a Kotlin Multiplatform library for breaking down your code into tree-structured lifecycle-aware business logic components (aka BLoC), with routing functionality and pluggable UI (Jetpack/Multiplatform Compose, Android Views, SwiftUI, JS React, etc.).
 
 Please see the [project website](https://arkivanov.github.io/Decompose/) for documentation and APIs. 
 
@@ -99,6 +99,10 @@ Please refer to the [Quick start](https://arkivanov.github.io/Decompose/getting-
 
 Check out the [Samples](https://arkivanov.github.io/Decompose/samples/) section of the docs for a full description of each sample.
 
+## Template
+
+Check out the [template repository](https://github.com/arkivanov/decompose-multiplatform-template) which may be used to kick-start a project for you.
+
 ## Articles
 
 - [Decompose — experiments with Kotlin Multiplatform lifecycle-aware components and navigation](https://proandroiddev.com/decompose-experiments-with-kotlin-multiplatform-lifecycle-aware-components-and-navigation-a04ef3c7f6a3?source=friends_link&sk=f7d289cc329b6c8a765fc049e36c313f)

decompose/api/android/decompose.api

@@ -70,6 +70,9 @@ public abstract interface annotation class com/arkivanov/decompose/FaultyDecompo
 public abstract interface annotation class com/arkivanov/decompose/InternalDecomposeApi : java/lang/annotation/Annotation {
 }
 
+public final class com/arkivanov/decompose/UtilsKt {
+}
+
 public final class com/arkivanov/decompose/errorhandler/ErrorHandlersKt {
 	public static final fun getOnDecomposeError ()Lkotlin/jvm/functions/Function1;
 	public static final fun setOnDecomposeError (Lkotlin/jvm/functions/Function1;)V

decompose/api/jvm/decompose.api

@@ -56,6 +56,9 @@ public abstract interface annotation class com/arkivanov/decompose/FaultyDecompo
 public abstract interface annotation class com/arkivanov/decompose/InternalDecomposeApi : java/lang/annotation/Annotation {
 }
 
+public final class com/arkivanov/decompose/UtilsKt {
+}
+
 public final class com/arkivanov/decompose/errorhandler/ErrorHandlersKt {
 	public static final fun getOnDecomposeError ()Lkotlin/jvm/functions/Function1;
 	public static final fun setOnDecomposeError (Lkotlin/jvm/functions/Function1;)V

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

@@ -1,6 +1,13 @@
 package com.arkivanov.decompose
 
 import com.arkivanov.essenty.lifecycle.Lifecycle
+import kotlin.reflect.KClass
+
+@InternalDecomposeApi
+fun Any.hashString(): String =
+    "${this::class.uniqueName ?: this::class.simpleName}_${hashCode().toString(radix = 36)}"
+
+internal expect val KClass<*>.uniqueName: String?
 
 internal expect fun Any.ensureNeverFrozen()
 

decompose/src/commonMain/kotlin/com/arkivanov/decompose/router/children/ChildNavState.kt

@@ -20,9 +20,7 @@ interface ChildNavState<out C : Any> {
      */
     enum class Status {
         /**
-         * The child component is instantiated and active. Its maximum lifecycle state is `RESUMED`,
-         * depending on the parent's lifecycle state. An active component can handle back button presses.
-         * The state of the component is saved when it switches from `ACTIVE` to any other status.
+         * The child component is destroyed but still managed, e.g. it's state may be saved and restored later.
          */
         DESTROYED,
 
@@ -33,8 +31,9 @@ interface ChildNavState<out C : Any> {
         INACTIVE,
 
         /**
-         * The child is created and may be resumed, depending on the lifecycle of the hosting component.
-         * Back button handling is enabled.
+         * The child component is instantiated and active. Its maximum lifecycle state is `RESUMED`,
+         * depending on the parent's lifecycle state. An active component can handle back button presses.
+         * The state of the component is saved when it switches from `ACTIVE` to any other status.
          */
         ACTIVE,
     }

decompose/src/jsMain/kotlin/com/arkivanov/decompose/Utils.kt

@@ -0,0 +1,6 @@
+package com.arkivanov.decompose
+
+import kotlin.reflect.KClass
+
+internal actual val KClass<*>.uniqueName: String?
+    get() = js.name

decompose/src/nonJsMain/kotlin/com/arkivanov/decompose/Utils.nonJs.kt

@@ -0,0 +1,6 @@
+package com.arkivanov.decompose
+
+import kotlin.reflect.KClass
+
+internal actual val KClass<*>.uniqueName: String?
+    get() = qualifiedName

deps.versions.toml

@@ -1,6 +1,6 @@
 [versions]
 
-decompose = "2.0.1-compose-experimental"
+decompose = "2.0.2-compose-experimental"
 kotlin = "1.8.20"
 essenty = "1.1.0"
 parcelizeDarwin = "0.1.4"

docs/component/state-preservation.md

@@ -4,9 +4,9 @@ Sometimes it might be necessary to preserve state or data in a component when it
 
 The `decompose` module adds Essenty's `state-keeper` module as `api` dependency, so you don't need to explicitly add it to your project. Please familiarise yourself with Essenty library, especially with the `StateKeeper`.
 
-## Usage example
+## Usage examples
 
-```kotlin
+```kotlin title="Saving state in a component"
 import com.arkivanov.decompose.ComponentContext
 import com.arkivanov.essenty.parcelable.Parcelable
 import com.arkivanov.essenty.parcelable.Parcelize
@@ -27,6 +27,46 @@ class SomeComponent(
 }
 ```
 
+```kotlin title="Saving state of a retained instance"
+import com.arkivanov.essenty.instancekeeper.InstanceKeeper
+import com.arkivanov.essenty.instancekeeper.getOrCreate
+import com.arkivanov.essenty.parcelable.Parcelable
+import com.arkivanov.essenty.parcelable.ParcelableContainer
+import com.arkivanov.essenty.parcelable.Parcelize
+import com.arkivanov.essenty.parcelable.consume
+import com.arkivanov.essenty.statekeeper.consume
+
+class SomeComponent(
+    componentContext: ComponentContext
+) : ComponentContext by componentContext {
+
+    private val statefulEntity =
+        instanceKeeper.getOrCreate {
+            SomeStatefulEntity(savedState = stateKeeper.consume(key = "SAVED_STATE"))
+        }
+
+    init {
+        stateKeeper.register(key = "SAVED_STATE", supplier = statefulEntity::saveState)
+    }
+}
+
+class SomeStatefulEntity(
+    savedState: ParcelableContainer?,
+) : InstanceKeeper.Instance {
+
+    var state: State = savedState?.consume() ?: State()
+        private set
+
+    fun saveState(): ParcelableContainer =
+        ParcelableContainer(state)
+
+    override fun onDestroy() {}
+
+    @Parcelize
+    data class State(val someValue: Int = 0) : Parcelable
+}
+```
+
 ## Darwin (Apple) targets support
 
 Decompose provides an experimental support of state preservation for all Darwin (Apple) targets. It works via `Essenty` library and [parcelize-darwin](https://github.com/arkivanov/parcelize-darwin) compiler plugin (from the same author). Please read the documentation of both before using state preservation on Darwin targets.