Merge pull request #2059 from element-hq/feature/fga/appyx_overlay

Appyx Overlay

libraries/architecture/build.gradle.kts

@@ -15,6 +15,7 @@
  */
 plugins {
     id("io.element.android-compose-library")
+    id("kotlin-parcelize")
 }
 
 android {

libraries/architecture/src/main/kotlin/io/element/android/libraries/architecture/BackstackNode.kt

@@ -1,57 +0,0 @@
-/*
- * Copyright (c) 2023 New Vector Ltd
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package io.element.android.libraries.architecture
-
-import androidx.compose.runtime.Stable
-import com.bumble.appyx.core.children.ChildEntry
-import com.bumble.appyx.core.modality.BuildContext
-import com.bumble.appyx.core.navigation.model.combined.plus
-import com.bumble.appyx.core.navigation.model.permanent.PermanentNavModel
-import com.bumble.appyx.core.node.Node
-import com.bumble.appyx.core.node.ParentNode
-import com.bumble.appyx.core.plugin.Plugin
-import com.bumble.appyx.navmodel.backstack.BackStack
-
-/**
- * This class is just an helper for configuring a backstack directly in the constructor.
- * With this we can more easily use constructor injection without having a secondary constructor to create the [BackStack] instance.
- * Can be used instead of [ParentNode] in flow nodes.
- */
-@Stable
-abstract class BackstackNode<NavTarget : Any>(
-    val backstack: BackStack<NavTarget>,
-    buildContext: BuildContext,
-    plugins: List<Plugin>,
-    val permanentNavModel: PermanentNavModel<NavTarget> = PermanentNavModel(emptySet(), null),
-    childKeepMode: ChildEntry.KeepMode = ChildEntry.KeepMode.KEEP,
-) : ParentNode<NavTarget>(
-    navModel = backstack + permanentNavModel,
-    buildContext = buildContext,
-    plugins = plugins,
-    childKeepMode = childKeepMode,
-) {
-    override fun onBuilt() {
-        super.onBuilt()
-        lifecycle.logLifecycle(this::class.java.simpleName)
-        whenChildAttached<Node> { _, child ->
-            // BackstackNode will be logged by their parent.
-            if (child !is BackstackNode<*>) {
-                child.lifecycle.logLifecycle(child::class.java.simpleName)
-            }
-        }
-    }
-}

libraries/architecture/src/main/kotlin/io/element/android/libraries/architecture/BaseFlowNode.kt

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2023 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.element.android.libraries.architecture
+
+import androidx.compose.animation.core.Spring
+import androidx.compose.animation.core.spring
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxScope
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.Stable
+import androidx.compose.ui.Modifier
+import com.bumble.appyx.core.children.ChildEntry
+import com.bumble.appyx.core.composable.Children
+import com.bumble.appyx.core.modality.BuildContext
+import com.bumble.appyx.core.navigation.model.combined.plus
+import com.bumble.appyx.core.navigation.model.permanent.PermanentNavModel
+import com.bumble.appyx.core.navigation.transition.TransitionHandler
+import com.bumble.appyx.core.node.Node
+import com.bumble.appyx.core.node.ParentNode
+import com.bumble.appyx.core.plugin.Plugin
+import com.bumble.appyx.navmodel.backstack.BackStack
+import com.bumble.appyx.navmodel.backstack.transitionhandler.rememberBackstackFader
+import com.bumble.appyx.navmodel.backstack.transitionhandler.rememberBackstackSlider
+import io.element.android.libraries.architecture.overlay.Overlay
+
+/**
+ * This class is a [ParentNode] that contains a [BackStack] and an [Overlay]. It is used to represent a flow in the app.
+ * Should be used instead of [ParentNode] in flow nodes.
+ */
+@Stable
+abstract class BaseFlowNode<NavTarget : Any>(
+    val backstack: BackStack<NavTarget>,
+    buildContext: BuildContext,
+    plugins: List<Plugin>,
+    val overlay: Overlay<NavTarget> = Overlay(null),
+    val permanentNavModel: PermanentNavModel<NavTarget> = PermanentNavModel(emptySet(), null),
+    childKeepMode: ChildEntry.KeepMode = ChildEntry.KeepMode.KEEP,
+) : ParentNode<NavTarget>(
+    navModel = overlay + backstack + permanentNavModel,
+    buildContext = buildContext,
+    plugins = plugins,
+    childKeepMode = childKeepMode,
+) {
+    override fun onBuilt() {
+        super.onBuilt()
+        lifecycle.logLifecycle(this::class.java.simpleName)
+        whenChildAttached<Node> { _, child ->
+            // BackstackNode will be logged by their parent.
+            if (child !is BaseFlowNode<*>) {
+                child.lifecycle.logLifecycle(child::class.java.simpleName)
+            }
+        }
+    }
+}
+
+@Composable
+inline fun <reified NavTarget : Any> BaseFlowNode<NavTarget>.BackstackView(
+    modifier: Modifier = Modifier,
+    transitionHandler: TransitionHandler<NavTarget, BackStack.State> = rememberBackstackSlider(
+        transitionSpec = { spring(stiffness = Spring.StiffnessMediumLow) },
+    ),
+) {
+    Children(
+        modifier = modifier,
+        navModel = backstack,
+        transitionHandler = transitionHandler,
+    )
+}
+
+@Composable
+inline fun <reified NavTarget : Any> BaseFlowNode<NavTarget>.OverlayView(
+    modifier: Modifier = Modifier,
+    transitionHandler: TransitionHandler<NavTarget, BackStack.State> = rememberBackstackFader(),
+) {
+    Children(
+        modifier = modifier,
+        navModel = overlay,
+        transitionHandler = transitionHandler,
+    )
+}
+
+@Composable
+inline fun <reified NavTarget : Any> BaseFlowNode<NavTarget>.BackstackWithOverlayBox(
+    modifier: Modifier = Modifier,
+    content: @Composable BoxScope.() -> Unit = {},
+) {
+    Box(modifier = modifier) {
+        BackstackView()
+        OverlayView()
+        content()
+    }
+}

libraries/architecture/src/main/kotlin/io/element/android/libraries/architecture/overlay/HideOverlayBackPressHandler.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2023 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.element.android.libraries.architecture.overlay
+
+import com.bumble.appyx.core.navigation.backpresshandlerstrategies.BaseBackPressHandlerStrategy
+import com.bumble.appyx.navmodel.backstack.BackStack
+import com.bumble.appyx.navmodel.backstack.BackStackElements
+import io.element.android.libraries.architecture.overlay.operation.Hide
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+
+class HideOverlayBackPressHandler<NavTarget : Any>
+    : BaseBackPressHandlerStrategy<NavTarget, BackStack.State>() {
+
+    override val canHandleBackPressFlow: Flow<Boolean> by lazy {
+        navModel.elements.map(::areThereElements)
+    }
+
+    private fun areThereElements(elements: BackStackElements<NavTarget>) =
+        elements.isNotEmpty()
+
+    override fun onBackPressed() {
+        navModel.accept(Hide())
+    }
+}

libraries/architecture/src/main/kotlin/io/element/android/libraries/architecture/overlay/Overlay.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2023 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.element.android.libraries.architecture.overlay
+
+import com.bumble.appyx.core.navigation.BaseNavModel
+import com.bumble.appyx.core.navigation.NavElements
+import com.bumble.appyx.core.navigation.backpresshandlerstrategies.BackPressHandlerStrategy
+import com.bumble.appyx.core.navigation.onscreen.OnScreenStateResolver
+import com.bumble.appyx.core.navigation.operationstrategies.ExecuteImmediately
+import com.bumble.appyx.core.navigation.operationstrategies.OperationStrategy
+import com.bumble.appyx.core.state.SavedStateMap
+import com.bumble.appyx.navmodel.backstack.BackStack
+import com.bumble.appyx.navmodel.backstack.BackStackOnScreenResolver
+
+class Overlay<NavTarget : Any>(
+    savedStateMap: SavedStateMap?,
+    key: String = requireNotNull(Overlay::class.qualifiedName),
+    backPressHandler: BackPressHandlerStrategy<NavTarget, BackStack.State> = HideOverlayBackPressHandler(),
+    operationStrategy: OperationStrategy<NavTarget, BackStack.State> = ExecuteImmediately(),
+    screenResolver: OnScreenStateResolver<BackStack.State> = BackStackOnScreenResolver,
+) : BaseNavModel<NavTarget, BackStack.State>(
+    backPressHandler = backPressHandler,
+    screenResolver = screenResolver,
+    operationStrategy = operationStrategy,
+    finalState = BackStack.State.DESTROYED,
+    savedStateMap = savedStateMap,
+    key = key,
+) {
+
+    override val initialElements: NavElements<NavTarget, BackStack.State>
+        get() = emptyList()
+}

libraries/architecture/src/main/kotlin/io/element/android/libraries/architecture/overlay/operation/Hide.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2023 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.element.android.libraries.architecture.overlay.operation
+
+import com.bumble.appyx.navmodel.backstack.BackStack
+import com.bumble.appyx.navmodel.backstack.BackStackElements
+import com.bumble.appyx.navmodel.backstack.activeIndex
+import io.element.android.libraries.architecture.overlay.Overlay
+import kotlinx.parcelize.Parcelize
+
+@Parcelize
+class Hide<T : Any> : OverlayOperation<T> {
+
+    override fun isApplicable(elements: BackStackElements<T>): Boolean =
+        elements.any { it.targetState == BackStack.State.ACTIVE }
+
+    override fun invoke(
+        elements: BackStackElements<T>
+    ): BackStackElements<T> {
+        val hideIndex = elements.activeIndex
+        require(hideIndex != -1) { "Nothing to hide, state=$elements" }
+        return elements.mapIndexed { index, element ->
+            when (index) {
+                hideIndex -> element.transitionTo(
+                    newTargetState = BackStack.State.DESTROYED,
+                    operation = this
+                )
+                else -> element
+            }
+        }
+    }
+
+    override fun equals(other: Any?): Boolean = this.javaClass == other?.javaClass
+
+    override fun hashCode(): Int = this.javaClass.hashCode()
+}
+
+fun <T : Any> Overlay<T>.hide() {
+    accept(Hide())
+}

libraries/architecture/src/main/kotlin/io/element/android/libraries/architecture/overlay/operation/OverlayOperation.kt

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2023 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.element.android.libraries.architecture.overlay.operation
+
+import com.bumble.appyx.core.navigation.Operation
+import com.bumble.appyx.navmodel.backstack.BackStack
+
+interface OverlayOperation<T> : Operation<T, BackStack.State>

libraries/architecture/src/main/kotlin/io/element/android/libraries/architecture/overlay/operation/Show.kt

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2023 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.element.android.libraries.architecture.overlay.operation
+
+import com.bumble.appyx.core.navigation.NavKey
+import com.bumble.appyx.navmodel.backstack.BackStack
+import com.bumble.appyx.navmodel.backstack.BackStackElement
+import com.bumble.appyx.navmodel.backstack.BackStackElements
+import com.bumble.appyx.navmodel.backstack.activeElement
+import io.element.android.libraries.architecture.overlay.Overlay
+import kotlinx.parcelize.Parcelize
+import kotlinx.parcelize.RawValue
+
+@Parcelize
+data class Show<T : Any>(
+    private val element: @RawValue T
+) : OverlayOperation<T> {
+
+    override fun isApplicable(elements: BackStackElements<T>): Boolean =
+        element != elements.activeElement
+
+    override fun invoke(elements: BackStackElements<T>): BackStackElements<T> = listOf(
+        BackStackElement(
+            key = NavKey(element),
+            fromState = BackStack.State.CREATED,
+            targetState = BackStack.State.ACTIVE,
+            operation = this
+        )
+    )
+}
+
+fun <T : Any> Overlay<T>.show(element: T) {
+    accept(Show(element))
+}