[#310] Ensure NavTarget and State are parcelable

Author: LachlanMcKee

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Pending changes
 
+- [#311](https://github.com/bumble-tech/appyx/pull/311) – **Breaking change**: `NavTarget` and `State` are now explicitly `Parcelable`. Please see this PR to see approaches to resolve any compilation issues you may notice.
 - [#287](https://github.com/bumble-tech/appyx/pull/287) – **Added**: Introduced a new `rememberCombinedHandler` implementation that takes an immutable list to avoid non-skippable compositions. The previous implementation is now deprecated.
 - [#287](https://github.com/bumble-tech/appyx/pull/287) – **Added**: `ImmutableList` has been added to avoid non-skippable compositions. 
 - [#289](https://github.com/bumble-tech/appyx/issues/289) – **Added**: Introduced `interop-rx3` for RxJava 3 support. This has identical functionality to `interop-rx2`.

documentation/navmodel/backstack.md

@@ -16,7 +16,8 @@ The back stack also supports different back press and operation strategies (see
 ## States
 
 ```kotlin
-enum class State {
+@Parcelize
+enum class State : Parcelable {
     CREATED, ACTIVE, STASHED, DESTROYED,
 }
 ```
@@ -33,7 +34,7 @@ Check out the apps in our [Coding challenges](../how-to-use-appyx/coding-challen
 As the back stack can never be empty, it's required to define an initial target.
 
 ```kotlin
-class BackStack<NavTarget : Any>(
+class BackStack<NavTarget : Parcelable>(
     initialElement: NavTarget,
     savedStateMap: SavedStateMap?,
     // Optional parameters are omitted
@@ -131,7 +132,7 @@ Effect on stack: depends on the contents of the stack:
 You can override the default strategy in the constructor. You're not limited to using the provided classes, feel free to implement your own.
 
 ```kotlin
-class BackStack<NavTarget : Any>(
+class BackStack<NavTarget : Parcelable>(
     /* ... */
     backPressHandler: BackPressHandlerStrategy<NavTarget, State> = PopBackPressHandler(),
     /* ... */
@@ -152,7 +153,7 @@ Serves as a no-op.
 You can override the default strategy in the constructor. You're not limited to using the provided classes, feel free to implement your own.
 
 ```kotlin
-class BackStack<NavTarget : Any>(
+class BackStack<NavTarget : Parcelable>(
     /* ... */
     operationStrategy: OperationStrategy<NavTarget, State> = ExecuteImmediately(),    
     /* ... */

documentation/navmodel/cards.md

@@ -15,13 +15,20 @@ The `Cards` NavModel is not currently published, however you can try it in `:sam
 ## States
 
 ```kotlin
-sealed class State {
+sealed class State: Parcelable {
+    @Parcelize
     data class Queued(val queueNumber: Int) : State()
+    @Parcelize
     object Bottom : State()
+    @Parcelize
     object Top : State()
+    @Parcelize
     object IndicateLike : State()
+    @Parcelize
     object IndicatePass : State()
+    @Parcelize
     object VoteLike : State()
+    @Parcelize
     object VotePass : State()
 }
 ```
@@ -35,7 +42,7 @@ sealed class State {
 Requires defining items that will be converted to profile cards. The first one in the list will become a `Top` card, the second one a `Bottom` card, the rest will be `Queued`. 
 
 ```kotlin
-class Cards<NavTarget : Any>(
+class Cards<NavTarget : Parcelable>(
     initialItems: List<NavTarget> = listOf(),
 ) : BaseNavModel<NavTarget, State>(
     screenResolver = CardsOnScreenResolver,

documentation/navmodel/custom.md

@@ -7,7 +7,7 @@ A step-by-step guide. You can also take a look at other existing examples to see
 Create the class; define your possible states; define your initial state. 
 
 ```kotlin
-class Foo<NavTarget : Any>(
+class Foo<NavTarget : Parcelable>(
     initialItems: List<NavTarget> = listOf(),
     savedStateMap: SavedStateMap?
 ) : BaseNavModel<NavTarget, Foo.State>(
@@ -17,7 +17,8 @@ class Foo<NavTarget : Any>(
 ) {
 
     // Your possible states for any single navigation target
-    enum class State {
+    @Parcelize
+    enum class State : Parcelable {
         CREATED, FOO, BAR, BAZ, DESTROYED;
     }
 
@@ -54,7 +55,7 @@ Define one or more operations.
 
 ```kotlin
 @Parcelize
-class SomeOperation<NavTarget : Any> : FooOperation<NavTarget> {
+class SomeOperation<NavTarget : Parcelable> : FooOperation<NavTarget> {
 
     override fun isApplicable(elements: FooElements<NavTarget>): Boolean =
         TODO("Define whether this operation is applicable given the current state")
@@ -74,7 +75,7 @@ class SomeOperation<NavTarget : Any> : FooOperation<NavTarget> {
 }
 
 // You can add an extension method for a leaner API
-fun <NavTarget : Any> Foo<NavTarget>.someOperation() {
+fun <NavTarget : Parcelable> Foo<NavTarget>.someOperation() {
     accept(FooOperation())
 }
 ```

documentation/navmodel/promoter.md

@@ -12,7 +12,8 @@ If you feel that this functionality should be part of the main library, please l
 ## States
 
 ```kotlin
-enum class State {
+@Parcelize
+enum class State : Parcelable {
     CREATED, STAGE1, STAGE2, STAGE3, STAGE4, SELECTED, DESTROYED
 }
 ```

documentation/navmodel/spotlight.md

@@ -9,7 +9,8 @@ It's great for flows or tabbed containers.
 ## States
 
 ```kotlin
-enum class State {
+@Parcelize
+enum class State : Parcelable {
     INACTIVE_BEFORE, ACTIVE, INACTIVE_AFTER;
 }
 ```
@@ -19,7 +20,7 @@ enum class State {
 Requires defining items and an active index.
 
 ```kotlin
-class Spotlight<NavTarget : Any>(
+class Spotlight<NavTarget : Parcelable>(
     items: List<NavTarget>,
     initialActiveIndex: Int = 0,
     savedStateMap: SavedStateMap?,
@@ -95,7 +96,7 @@ Replaces elements held by the spotlight instance with a new list. Transitions ne
 You can override the default strategy in the constructor. You're not limited to using the provided classes, feel free to implement your own.
 
 ```kotlin
-class Spotlight<NavTarget : Any>(
+class Spotlight<NavTarget : Parcelable>(
     /* ... */
     backPressHandler: BackPressHandlerStrategy<NavTarget, State> = GoToDefault(
         initialActiveIndex
@@ -118,7 +119,7 @@ Runs a `Previous` operation.
 You can override the default strategy in the constructor. You're not limited to using the provided classes, feel free to implement your own.
 
 ```kotlin
-class Spotlight<NavTarget : Any>(
+class Spotlight<NavTarget : Parcelable>(
     /* ... */
     operationStrategy: OperationStrategy<NavTarget, State> = ExecuteImmediately(),    
     /* ... */

documentation/navmodel/tiles.md

@@ -12,7 +12,8 @@ If you feel that this functionality should be part of the main library, please l
 ## States
 
 ```kotlin
-enum class State {
+@Parcelize
+enum class State : Parcelable {
     CREATED, STANDARD, SELECTED, DESTROYED
 }
 ```

documentation/ui/children-view.md

@@ -84,7 +84,7 @@ override fun View(modifier: Modifier) {
 }
 
 @Composable
-private fun GridExample(elements: List<NavElement<NavTarget, out Any?>>) {
+private fun GridExample(elements: List<NavElement<NavTarget, out Parcelable?>>) {
     LazyVerticalGrid(
         columns = Fixed(2),
         modifier = Modifier.fillMaxSize(),

libraries/core/src/androidTest/kotlin/com/bumble/appyx/core/node/PermanentChildTest.kt

@@ -13,6 +13,7 @@ import com.bumble.appyx.core.AppyxTestScenario
 import com.bumble.appyx.core.children.nodeOrNull
 import com.bumble.appyx.core.modality.BuildContext
 import com.bumble.appyx.core.navigation.EmptyNavModel
+import com.bumble.appyx.core.navigation.EmptyState
 import kotlinx.parcelize.Parcelize
 import org.junit.Assert.assertEquals
 import org.junit.Rule
@@ -50,7 +51,7 @@ class PermanentChildTest {
         buildContext: BuildContext,
     ) : ParentNode<TestParentNode.NavTarget>(
         buildContext = buildContext,
-        navModel = EmptyNavModel<NavTarget, Any>(),
+        navModel = EmptyNavModel<NavTarget, EmptyState>(),
     ) {
 
         @Parcelize

libraries/core/src/main/kotlin/com/bumble/appyx/core/children/ChildEntry.kt

@@ -1,11 +1,12 @@
 package com.bumble.appyx.core.children
 
+import android.os.Parcelable
 import com.bumble.appyx.core.navigation.NavKey
 import com.bumble.appyx.core.node.Node
 import com.bumble.appyx.core.state.SavedStateMap
 
 // custom equals/hashCode for MutableStateFlow and equality checks
-sealed class ChildEntry<T> {
+sealed class ChildEntry<T : Parcelable> {
     abstract val key: NavKey<T>
 
     override fun equals(other: Any?): Boolean =
@@ -18,12 +19,12 @@ sealed class ChildEntry<T> {
         "$key@${javaClass.simpleName}"
 
     /** All public APIs should return this type of child which is ready to work with. */
-    class Initialized<T>(
+    class Initialized<T : Parcelable>(
         override val key: NavKey<T>,
         val node: Node,
     ) : ChildEntry<T>()
 
-    class Suspended<T>(
+    class Suspended<T : Parcelable>(
         override val key: NavKey<T>,
         val savedState: SavedStateMap?,
     ) : ChildEntry<T>()