Merge pull request #267 from orcinusbr/add/platform-animator

Add platform sequential animation API

gradle/libs.versions.toml

@@ -4,6 +4,7 @@ android-activity-ktx = { group = "androidx.activity", name = "activity-ktx", ver
 android-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "android-activity" }
 android-appcompat = { group = "androidx.appcompat", name = "appcompat", version = "1.6.1" }
 android-browser = { group = "androidx.browser", name = "browser", version = "1.7.0" }
+android-compose-animation = { group = "androidx.compose.animation", name = "animation", version.ref = "android-compose" }
 android-compose-foundation = { group = "androidx.compose.foundation", name = "foundation", version.ref = "android-compose" }
 android-compose-material = { group = "androidx.compose.material", name = "material", version.ref = "android-compose" }
 android-compose-material-icons = { group = "androidx.compose.material", name = "material-icons-extended", version = "1.5.4" }

platform/animator/build.gradle.kts

@@ -0,0 +1,41 @@
+/*
+ * Copyright © 2024 Orca
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the
+ * GNU General Public License as published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+ * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program. If
+ * not, see https://www.gnu.org/licenses.
+ */
+
+plugins {
+ alias(libs.plugins.android.library)
+ alias(libs.plugins.kotlin.android)
+}
+
+android {
+ buildFeatures.compose = true
+ composeOptions.kotlinCompilerExtensionVersion = libs.versions.android.compose.compiler.get()
+ defaultConfig.testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+}
+
+dependencies {
+ androidTestImplementation(libs.android.compose.material3)
+ androidTestImplementation(libs.android.compose.ui.test.junit)
+ androidTestImplementation(libs.android.compose.ui.test.manifest)
+ androidTestImplementation(libs.assertk)
+ androidTestImplementation(libs.kotlin.test)
+
+ implementation(libs.android.compose.animation)
+ implementation(project(":ext:coroutines"))
+
+ testImplementation(libs.assertk)
+ testImplementation(libs.kotlin.coroutines.test)
+ testImplementation(libs.kotlin.test)
+ testImplementation(libs.turbine)
+}

platform/animator/src/androidTest/java/com/jeanbarrossilva/orca/platform/animator/AnimatorTests.kt

@@ -0,0 +1,53 @@
+/*
+ * Copyright © 2024 Orca
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the
+ * GNU General Public License as published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+ * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program. If
+ * not, see https://www.gnu.org/licenses.
+ */
+
+package com.jeanbarrossilva.orca.platform.animator
+
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.ui.test.junit4.createComposeRule
+import assertk.assertThat
+import assertk.assertions.isEqualTo
+import com.jeanbarrossilva.orca.platform.animator.animation.Motion
+import com.jeanbarrossilva.orca.platform.animator.animation.animatable.Animatables
+import kotlin.test.Test
+import org.junit.Rule
+
+internal class AnimatorTests {
+ @get:Rule val composeRule = createComposeRule()
+
+ @Test
+ fun providesAnimatablesForStillMotion() {
+ composeRule.setContent {
+ Animator(Motion.Still) {
+ DisposableEffect(Unit) {
+ assertThat(it).isEqualTo(Animatables(Motion.Still))
+ onDispose {}
+ }
+ }
+ }
+ }
+
+ @Test
+ fun providesAnimatablesForMovingMotion() {
+ composeRule.setContent {
+ Animator {
+ DisposableEffect(Unit) {
+ assertThat(it).isEqualTo(Animatables(Motion.Moving))
+ onDispose {}
+ }
+ }
+ }
+ }
+}

platform/animator/src/androidTest/java/com/jeanbarrossilva/orca/platform/animator/animation/animatable/AnimatableTests.kt

@@ -0,0 +1,62 @@
+/*
+ * Copyright © 2024 Orca
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the
+ * GNU General Public License as published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+ * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program. If
+ * not, see https://www.gnu.org/licenses.
+ */
+
+package com.jeanbarrossilva.orca.platform.animator.animation.animatable
+
+import androidx.compose.animation.core.AnimationConstants.DefaultDurationMillis
+import androidx.compose.animation.core.tween
+import androidx.compose.animation.fadeIn
+import androidx.compose.material3.Text
+import androidx.compose.runtime.remember
+import androidx.compose.ui.test.assertIsDisplayed
+import androidx.compose.ui.test.junit4.createComposeRule
+import androidx.compose.ui.test.onNodeWithText
+import assertk.assertThat
+import assertk.assertions.isTrue
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.test.UnconfinedTestDispatcher
+import kotlinx.coroutines.test.runTest
+import org.junit.Rule
+import org.junit.Test
+
+internal class AnimatableTests {
+ @get:Rule val composeRule = createComposeRule()
+
+ @Test
+ fun showsContentImmediately() {
+ composeRule
+ .apply { setContent { remember(Animatable::Moving).Animate { Text("1️⃣0️⃣") } } }
+ .onNodeWithText("1️⃣0️⃣")
+ .assertIsDisplayed()
+ }
+
+ @Test
+ fun waitsForAnimation() {
+ val animatable = Animatable.Moving()
+ var hasAnimationFinished = false
+ runTest(@OptIn(ExperimentalCoroutinesApi::class) UnconfinedTestDispatcher()) {
+ launch {
+ animatable.waitForAnimation()
+ hasAnimationFinished = true
+ }
+ launch {
+ composeRule.setContent { animatable.Animate(fadeIn(tween())) {} }
+ composeRule.mainClock.advanceTimeBy(milliseconds = DefaultDurationMillis.toLong())
+ assertThat(hasAnimationFinished).isTrue()
+ }
+ }
+ }
+}

platform/animator/src/main/AndroidManifest.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ ~ Copyright © 2024 Orca
+ ~
+ ~ This program is free software: you can redistribute it and/or modify it under the terms of the
+ ~ GNU General Public License as published by the Free Software Foundation, either version 3 of the
+ ~ License, or (at your option) any later version.
+ ~
+ ~ This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+ ~ even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ ~ General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License along with this program. If
+ ~ not, see https://www.gnu.org/licenses.
+ -->
+
+<manifest />

platform/animator/src/main/java/com/jeanbarrossilva/orca/platform/animator/Animator.kt

@@ -0,0 +1,79 @@
+/*
+ * Copyright © 2024 Orca
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the
+ * GNU General Public License as published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+ * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program. If
+ * not, see https://www.gnu.org/licenses.
+ */
+
+package com.jeanbarrossilva.orca.platform.animator
+
+import androidx.compose.animation.EnterTransition
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import com.jeanbarrossilva.orca.platform.animator.animation.Motion
+import com.jeanbarrossilva.orca.platform.animator.animation.animatable.Animatable
+import com.jeanbarrossilva.orca.platform.animator.animation.animatable.Animatables
+import com.jeanbarrossilva.orca.platform.animator.animation.timing.after
+import com.jeanbarrossilva.orca.platform.animator.animation.timing.immediately
+
+/**
+ * Animator is an Orca-specific animation API built on top of Jetpack Compose's that facilitates the
+ * orchestration of sequential [EnterTransition]s that depend on others for them to start running.
+ *
+ * It works by providing [Animatable]s (not to be confused with
+ * [androidx.compose.animation.Animatable]) to the given [content], each intended to arbitrarily
+ * refer to a [Composable] that will have its visibility toggled on alongside the execution of an
+ * [EnterTransition].
+ *
+ * [Composable]s can have their entrance animated by being provided as the content of their assigned
+ * [Animatable]'s [Animatable.Animate]. For example:
+ * ```kotlin
+ * Animator { (greeting) ->
+ * greeting.Animate(fadeIn()) {
+ * Text("Hello, world!")
+ * }
+ * }
+ * ```
+ *
+ * In this case, the greeting would fade in [immediately], since it doesn't depend on other
+ * animations and no posterior delay has been specified. Similarly, the following is how it would be
+ * done if the greeting was to be displayed only 2 seconds [after] another [Composable]'s animation
+ * has finished running:
+ * ```kotlin
+ * Animator { (emoji, greeting) ->
+ * emoji.Animate(fadeIn()) {
+ * Text("🌎")
+ * }
+ *
+ * greeting.Animate(fadeIn(), after(emoji) + 2.seconds) {
+ * Text("Hello, world!")
+ * }
+ * }
+ * ```
+ *
+ * Note that this [Composable], [Animator], serves merely as an entrypoint to the overall API and
+ * doesn't have any intrinsic behavior other than just showing the [content] and providing a
+ * remembered instance of [Animatables] to it.
+ *
+ * @param motion Indicates whether the specified animations should be run or if the [Composable]s
+ * should be shown instantly; defaults to [Motion.Moving], which, as expected from an animation
+ * API, turns them on and plays the [EnterTransition]s as they were declared to be performed.
+ *
+ * Setting it to [Motion.Still] for disabling them might be useful for both previewing the final
+ * state of the animated [Composable]s and testing.
+ *
+ * @param content Content to be shown in which [Animatable]-based animations can be run.
+ */
+@Composable
+fun Animator(motion: Motion = Motion.Moving, content: @Composable (Animatables) -> Unit) {
+ val animatables = remember(motion) { Animatables(motion) }
+ content(animatables)
+}

platform/animator/src/main/java/com/jeanbarrossilva/orca/platform/animator/animation/Animation.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright © 2024 Orca
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the
+ * GNU General Public License as published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+ * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program. If
+ * not, see https://www.gnu.org/licenses.
+ */
+
+package com.jeanbarrossilva.orca.platform.animator.animation
+
+import androidx.compose.runtime.Immutable
+
+/** Stage in which an animation can be. */
+@Immutable
+internal enum class Animation {
+ /** States that an animation hasn't started running. */
+ Idle,
+
+ /** Denotes that an animation has been requested to be run but hasn't started yet. */
+ Prepared,
+
+ /** Indicates that an animation is in progress. */
+ Ongoing,
+
+ /** Represents that an animation has finished running. */
+ Ended
+}

platform/animator/src/main/java/com/jeanbarrossilva/orca/platform/animator/animation/Motion.kt

@@ -0,0 +1,41 @@
+/*
+ * Copyright © 2024 Orca
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the
+ * GNU General Public License as published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
+ * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program. If
+ * not, see https://www.gnu.org/licenses.
+ */
+
+package com.jeanbarrossilva.orca.platform.animator.animation
+
+import com.jeanbarrossilva.orca.platform.animator.animation.animatable.Animatable
+
+/** Indicates whether animations should be run or not. */
+enum class Motion {
+ /** Denotes that animations should be enabled and run as expected. */
+ Moving {
+ override fun createAnimatable(): Animatable {
+ return Animatable.Moving()
+ }
+ },
+
+ /**
+ * Denotes that all animations should be disabled and that the content should be displayed
+ * instantly.
+ */
+ Still {
+ override fun createAnimatable(): Animatable {
+ return Animatable.Still()
+ }
+ };
+
+ /** Creates an [Animatable]. */
+ internal abstract fun createAnimatable(): Animatable
+}