Moving Animation into Variant Triggers (Deprecating Global .animate())

[tilucasoli]

Current State

Animation in Mix is declared as a global modifier on the Style:

final style = BoxStyler()
    .color(Colors.black)
    .scale(1)
    .onHovered(BoxStyler().color(Colors.blue).scale(1.5))
    .animate(.spring(800.ms));  // ← one config for every transition this style makes

StyleAnimationBuilder picks up $animation from the resolved StyleSpec and drives all transitions with the same config — whether the change came from a hover, a dark mode switch, an orientation flip, or a plain state rebuild.

This works for the common case but the model has a fundamental flaw: the animation config is attached to the style, not to the trigger. The trigger is the variant. The animation should live there.

---

The Goal

Deprecate and eventually remove the top-level .animate() method. Animation is declared at the variant level:

// Before
BoxStyler()
    .color(Colors.black)
    .scale(1)
    .onHovered(BoxStyler().color(Colors.blue).scale(1.5))
    .animate(.spring(800.ms));

// After
BoxStyler()
    .color(Colors.black)
    .scale(1)
    .onHovered(
      BoxStyler().color(Colors.blue).scale(1.5),
      animation: .spring(800.ms),
    );

---

Why this is better

1. Trigger and animation are co-located

.onHovered(styler:, animation:) tells you what changes and how it moves in one place. You don't have to hunt for the .animate() call at the end of the chain to understand the transition.

2. Different transitions can animate differently

BoxStyler()
    .color(Colors.white)
    .onHovered(
      BoxStyler().color(Colors.blue).scale(1.05),
      animation: .spring(600.ms),          // interactive: springy
    )
    .onPressed(
      BoxStyler().color(Colors.indigo).scale(0.95),
      animation: .spring(150.ms, bounce: 0), // feedback: fast, no bounce
    )
    .onDark(
      BoxStyler().color(Colors.grey.shade900),
      // no animation — theme switch is instant
    );

This is impossible to express cleanly today. You can't give .onHovered a spring and .onDark nothing with a single global config.

3. No hidden blast radius

Today, .animate(.spring(800.ms)) silently animates dark/light transitions, orientation changes, breakpoint switches — anything that triggers a style rebuild. Developers typically think they're animating their hover, not their theme. Per-variant animation is explicit by definition.

4. The model is complete without a global escape hatch

A global "animate everything" config is appealing as a shortcut but it hides what is actually being animated. Making animation explicit per-trigger is a small cost at the call site and a large gain in clarity and debuggability.

---

What Happens to Implicit State Animations?

Not everything in Mix goes through a variant. Today you can write:

BoxStyler()
    .scale(appear ? 1.0 : 0.1)
    .opacity(appear ? 1.0 : 0.0)
    .animate(.easeInOut(600.ms));

The animated values come from a Flutter state variable. There is no ContextVariant being toggled. If .animate() is removed as-is, this pattern breaks.

The recommended fix: keep .animate() but require a trigger. The trigger makes the animation explicit — it fires only when the trigger changes, not on every style rebuild. Two possible shapes for the trigger:

---

Option A — Listenable trigger

// Notifier lives in widget state
final _appear = ValueNotifier(false);

BoxStyler()
    .scale(_appear.value ? 1.0 : 0.1)
    .opacity(_appear.value ? 1.0 : 0.0)
    .animate(.easeInOut(600.ms), trigger: _appear);

The animation fires whenever _appear emits. The StyleAnimationBuilder subscribes to the Listenable directly, independent of the widget rebuild cycle.

Pros:

• Consistent with phaseAnimation and keyframeAnimation, which already use Listenable? trigger.
• The animation controller is decoupled from setState — the notifier can change without rebuilding the widget tree.
• Explicit: you can see exactly what drives the animation.

Cons:

• Requires converting plain state booleans/values to ValueNotifier. More boilerplate for simple cases.
• Developers holding a bool in setState need a migration step.

---

Option B — Plain value trigger

// appear is a plain bool from setState
BoxStyler()
    .scale(appear ? 1.0 : 0.1)
    .opacity(appear ? 1.0 : 0.0)
    .animate(.easeInOut(600.ms), trigger: appear);

The framework compares the trigger value between rebuilds (via ==). When it changes, the animation fires. Similar to how Flutter's ImplicitlyAnimatedWidget works — set a value, it animates to it.

Pros:

• Zero boilerplate increase. Works with any existing state variable.
• Ergonomically closest to the current .animate() usage.
• Supports continuous values naturally: trigger: counter works as well as trigger: appear.

Cons:

• The trigger comparison happens inside StyleAnimationBuilder.didUpdateWidget, which means it's tied to the widget rebuild cycle. If the value changes without a rebuild, nothing fires.
• Less consistent with phaseAnimation/keyframeAnimation which use Listenable.
• Equality comparison can be surprising for complex objects.

---