Unify/Animations.md

Animations in Unify

Unify's animation system provides a declarative and flexible way to apply smooth transitions, visual effects, and interactive animations to your UI components. Whether it's for simple property changes, complex transitions, or interactive user feedback, Unify makes it easy to animate your components in a clear and structured way.

---

1. Introduction to Animations

Animations in Unify are object-driven, meaning animations are attached directly to Unify objects such as panels, buttons, and other UI components. The animation system uses keyframes to define transitions over time, allowing properties like opacity, transform, background, etc., to change smoothly.

Animations are executed based on events (e.g., click, load, hover) or can be triggered explicitly using the play() method.

---

2. Basic Animation Example

To define an animation, you typically use the createAnimation method, which creates a new animation instance. You can then define keyframes and set the properties for the element at various points during the animation.

Example: Color Change Animation

Here’s an example where we animate the background color of an element from blue to green:

class ColorChangeAnimation {

    element = document.createElement("div");
    width = 100;
    height = 100;
    margin = 20;

    create() {
        // Create the animation
        this.animation = this.createAnimation("colorChange");

        // Define keyframes
        var key = this.animation.createKeyFrame(0);
        key.setProperty("background", "#03a9f4"); // Initial color

        key = this.animation.createKeyFrame(100);
        key.setProperty("background", "#a6e22e"); // Final color
    }

    async click() {
        // Play the animation over 2 seconds when clicked
        await this.animation.play("2s");
    }
}

Key Concepts:

• Create the animation: The createAnimation("colorChange") method creates a new animation instance.
• Define keyframes: Keyframes define the start and end states of the animation (e.g., background changing from blue to green).
• Trigger the animation: The play() method starts the animation and allows you to define its duration (e.g., 2s for 2 seconds).

---

3. Animating Multiple Properties

You can animate multiple properties simultaneously by setting multiple keyframes for different CSS properties. This allows you to create more complex animations that change several aspects of the UI at once.

Example: Fading and Scaling

Here’s an example of an animation that fades an element in while simultaneously scaling it up:

class FadeAndScale {

    element = document.createElement("div");
    width = 100;
    height = 100;
    margin = 20;

    create() {
        // Create the animation
        this.animation = this.createAnimation("fadeAndScale");

        // Fade in
        var key = this.animation.createKeyFrame(0);
        key.setProperty("opacity", "0");
        key.setProperty("transform", "scale(0.5)");

        // Fade and scale up
        key = this.animation.createKeyFrame(100);
        key.setProperty("opacity", "1");
        key.setProperty("transform", "scale(1)");
    }

    async click() {
        // Play the fade and scale animation
        await this.animation.play("2s");
    }
}

In this example:

• Opacity and transform properties are animated together.
• The element fades in from opacity: 0 to opacity: 1 while scaling from scale(0.5) to scale(1).

---

4. Triggering Animations Based on Events

You can trigger animations in response to various user events like click, hover, or focus. This makes the animations interactive, responding to user actions.

Example: Button Click Animation

Let’s animate a button's background color when it’s clicked:

import button from '/elements/button.js';

export default class AnimatedButton extends button {

    label = "Click Me";

    async click() {
        // Create a new animation
        this.animation = this.createAnimation("buttonClick");

        var key = this.animation.createKeyFrame(0);
        key.setProperty("background-color", "#03a9f4"); // Initial color

        key = this.animation.createKeyFrame(100);
        key.setProperty("background-color", "#f92672"); // Final color

        // Play the animation for 2 seconds
        await this.animation.play("2s");
    }
}

When the user clicks the button, the click() method triggers the animation that changes the background color from blue (#03a9f4) to red (#f92672).

---

5. Sequential and Chained Animations

You can also chain animations together to create more complex effects. For instance, you can have one animation complete before the next one starts.

Example: Sequential Animations

class SequentialAnimations {

    element = document.createElement("div");
    width = 100;
    height = 100;
    margin = 20;

    create() {
        // Animation 1: Fade in
        this.animation1 = this.createAnimation("fadeIn");
        var key = this.animation1.createKeyFrame(0);
        key.setProperty("opacity", "0");

        key = this.animation1.createKeyFrame(100);
        key.setProperty("opacity", "1");

        // Animation 2: Scale up
        this.animation2 = this.createAnimation("scaleUp");
        key = this.animation2.createKeyFrame(0);
        key.setProperty("transform", "scale(0.5)");

        key = this.animation2.createKeyFrame(100);
        key.setProperty("transform", "scale(1)");
    }

    async click() {
        // Play fade-in animation first
        await this.animation1.play("2s");

        // After fade-in, play scale-up animation
        await this.animation2.play("2s");

        alert("Both animations are complete!");
    }
}

Explanation:

• Sequential Execution: The await ensures that the animations play one after another. First, the fade-in animation plays, followed by the scale-up animation.
• Multiple Animations: The keyframes for each animation are created independently, and their respective properties change over time.

---

6. Animating Transitions Between States

Animations are often used for transitioning between different states of an application, such as showing or hiding a panel, or transitioning between pages.

Example: Sliding In a Panel

import panel from '/elements/panel.js';

export default class SlidePanel extends panel {
    isOpen = false;

    async click() {
        if (!this.isOpen) {
            // Slide in animation
            this.animation = this.createAnimation("slideIn");
            var key = this.animation.createKeyFrame(0);
            key.setProperty("transform", "translateX(100%)");

            key = this.animation.createKeyFrame(100);
            key.setProperty("transform", "translateX(0)");

            await this.animation.play("0.5s");
            this.isOpen = true;
        } else {
            // Slide out animation
            this.animation = this.createAnimation("slideOut");
            var key = this.animation.createKeyFrame(0);
            key.setProperty("transform", "translateX(0)");

            key = this.animation.createKeyFrame(100);
            key.setProperty("transform", "translateX(100%)");

            await this.animation.play("0.5s");
            this.isOpen = false;
        }
    }
}

Steps:

1. Slide In: The panel slides in from the right (by transitioning translateX(100%) to translateX(0)).
2. Slide Out: When clicked again, the panel slides out of view (by transitioning translateX(0) to translateX(100%)).
3. Interactive: The isOpen flag determines whether to slide in or slide out, toggling the state.

---

7. Conclusion

Unify’s animation system provides a flexible, declarative approach to animating UI elements. Whether you're animating simple property changes or complex transitions between multiple states, you can easily add animations to your UI.

Key features:

• Multiple keyframes to animate multiple properties simultaneously.
• Event-driven animations triggered by user interactions (e.g., clicks, page loads).
• Sequential and parallel animations to create complex visual effects.
• Smooth transitions for UI states like opening/closing panels or transitioning between pages.

By leveraging Unify’s animation system, you can craft engaging and interactive user experiences with minimal effort.