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**:

```js
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:

```js
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:

```js
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

```js
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

```js
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.