Koreography

Koreography is a Kotlin DSL for orchestrating low-level Jetpack Compose Animatable objects.

• Move: The fundamental unit of animation. It targets a specific Animatable with a targetValue and an animationSpec.
• Choreography: A composition of moves. You can define how these moves relate to each other using sequentialMoves (one after another) or parallelMoves (all at once).
• Nesting: You can nest parallelMoves and sequentialMoves to create complex, hierarchical animation sequences.

Koreography is available on Maven Central. Add the following dependency to your build.gradle file to use the library in your Android Compose project.

implementation 'io.github.sagar-viradiya:koreography:0.3.0'

The Move interface is the core abstraction for defining animations in Koreography. It uses a DSL-like structure to compose different types of animation behaviors:

1. Single Moves: Animating a single Animatable to a targetValue.
2. Sequential Moves: A group of moves that execute one after another.
3. Parallel Moves: A group of moves that execute at the same time.

You build these by calling DSL functions like move(), sequentialMoves(), and parallelMoves() within a scope that manages a list of moves.

// Conceptual structure of Move composition
sequentialMoves { 
    move(animatable1, target1)
    parallelMoves {
        move(animatable2, target2)
        move(animatable3, target3)
    }
}

To animate multiple properties one after another, use the rememberKoreography block and declare move calls directly within it. Each move will wait for the previous one to complete.

val alphaAnimatable = remember { Animatable(0f) }
val scaleAnimatable = remember { Animatable(0f) }

val koreography = rememberKoreography {
    move(
        animatable = alphaAnimatable,
        targetValue = 1f,
        animationSpec = tween(500)
    )
    
    move(
        animatable = scaleAnimatable,
        targetValue = 2f,
        animationSpec = tween(500)
    )
}

To animate multiple properties at the same time, wrap your move calls inside a parallelMoves block within rememberKoreography.

val alphaAnimatable = remember { Animatable(0f) }
val scaleAnimatable = remember { Animatable(0f) }

val koreography = rememberKoreography {
    parallelMoves {
        move(
            animatable = alphaAnimatable,
            targetValue = 1f,
            animationSpec = tween(500)
        )
        
        move(
            animatable = scaleAnimatable,
            targetValue = 2f,
            animationSpec = tween(500)
        )
    }
}

Once a choreography is defined using rememberKoreography, you can trigger it using the following methods. Note that you must provide a coroutineScope (typically obtained via rememberCoroutineScope()) to handle the animation lifecycle.

// One time execution
koreography.dance(scope = coroutineScope) { 
    // Optional: callback when finished 
}

// Repeat execution a specific number of times
koreography.repeatDance(count = 3, scope = coroutineScope) { 
    // Optional: callback when finished 
}

// Infinite execution (runs as long as the composition is alive)
koreography.danceForever(scope = coroutineScope) { 
    // Optional: callback when finished 
}

Use the LaunchKoreography composable to trigger a choreography whenever a specific state changes. This behaves similarly to the standard Compose LaunchedEffect API.

val alphaAnimatable = remember { Animatable(0f) }
val scaleAnimatable = remember { Animatable(0f) }

// The choreography inside this block will re-run whenever 'state' changes
LaunchKoreography(state) {
    move(
        animatable = alphaAnimatable,
        targetValue = 1f,
        animationSpec = tween(500)
    )
    
    move(
        animatable = scaleAnimatable,
        targetValue = 2f,
        animationSpec = tween(500)
    )
}

The parallelMoves function allows you to group multiple Move objects so they execute simultaneously. Inside the parallelMoves block, you can call move(), sequentialMoves(), or nested parallelMoves().

Usage: Call parallelMoves { ... } and define the parallel animations within the lambda.

parallelMoves {
    move(animatableA, 10f)
    move(animatableB, 20f)
}

Use the koreography function to define a sequence of animation moves using a Kotlin DSL. The DSL operates on a Move.SequentialMoves object, allowing you to compose sequential and parallel animations. This returns a Koreography instance that can be executed later.

val myKoreography = koreography<Float, AnimationVector1D> {
    // Define moves here using the DSL
}

When working within a @Composable function, use rememberKoreography to instantiate and remember your choreography definition across recompositions.

@Composable
fun MyComponent() {
    val myKoreography = rememberKoreography<Float, AnimationVector1D> {
        // Define moves here
    }
    // ...
}

The sequentialMoves function allows you to group multiple Move objects so they execute in order. Inside the sequentialMoves block, you can call move(), parallelMoves(), or even nested sequentialMoves().

Usage: Call sequentialMoves { ... } and define the sequence of animations within the lambda.

sequentialMoves {
    move(animatableA, 10f)
    move(animatableB, 20f)
}