Animation helpers for declarative runtime transitions.

Basics

Animation keyframes are written with ordinary Emerge attrs. When written inline, keyframes are attr lists such as [Transform.move_x(-40), Transform.alpha(0.0)]. Maps are also accepted when building specs programmatically.

Each animation spec needs:

• at least 2 non-empty keyframes
• a positive duration in milliseconds
• a curve: :linear, :ease_in, :ease_out, or :ease_in_out
• an optional repeat: :once, :loop, or a positive integer

A positive integer runs that many times and then clamps to the last keyframe. Enter animations don't hold their last keyframe; see "Animate Enter".

These examples assume use Emerge.UI.

Keyframes

Every keyframe must use the same attribute set throughout the animation. Width and height accept pixels, content, fill and weighted fill; other attrs must stay compatible.

Examples:

• widths/heights can animate between pixels, content, fill and weighted fill
• min/2 and max/2 remain static layout expressions and cannot be animation endpoints
• padding(8) can animate to padding(16), but not to padding_each(8, 12, 8, 12)
• solid backgrounds can animate to other solid backgrounds
• Background.color(gradient([...])) can animate to another gradient background with the same number of stops (colors and angle are interpolated)
• image backgrounds must keep the same source and fit across keyframes
• Border.shadow/1 and Border.glow/2 must keep the same shadow count in each keyframe

Animate

animate/4 runs during normal retained updates. Use it for looping motion and other ongoing transitions.

el(
  [
    Animation.animate(
      [
        [Transform.move_x(-60), Transform.alpha(0.4)],
        [Transform.move_x(60), Transform.alpha(1.0)],
        [Transform.move_x(-60), Transform.alpha(0.4)]
      ],
      3000,
      :linear,
      :loop
    ),
    Background.color(color(:teal, 400)),
    Border.rounded(12),
    padding(10)
  ],
  text("Looping")
)

Animate Enter

animate_enter/4 starts when an element first mounts. It does not start if it is added later to an already retained node.

The enter spec is captured at mount time, so changing it later does not affect the currently running enter animation.

When an enter animation finishes, the element renders with its plain attrs again. To end on a different value, set it as a plain attr too.

If both animate_enter/4 and animate/4 are present, the regular animation waits for the enter animation to finish and then starts from zero progress. Fields can hand off separately: geometry may remain held for a sibling while an unrelated paint field starts its regular clock.

el(
  [
    Animation.animate_enter(
      [
        [Transform.move_y(20), Transform.alpha(0.0)],
        [Transform.move_y(0), Transform.alpha(1.0)]
      ],
      180,
      :ease_out
    )
  ],
  text("Entering")
)

Animate Exit

animate_exit/4 starts when an element is removed from the tree. Emerge keeps rendering the element until the exit animation finishes.

animate_exit/4 must use :once and is not allowed on the viewport root.

el(
  [
    Animation.animate_exit(
      [
        [Transform.alpha(1.0)],
        [Transform.alpha(0.0)]
      ],
      120,
      :linear
    )
  ],
  text("Leaving")
)

Animatable Attrs

Animation keyframes support these public attr families:

• layout: width/1, height/1, padding/1, padding_each/4, spacing/1, spacing_xy/2
• background: Background.*
• border: Border.rounded/1, Border.rounded_each/4, Border.width/1, Border.width_each/4, Border.color/1, Border.shadow/1, Border.glow/2
• font and svg color: Font.size/1, Font.color/1, Font.letter_spacing/1, Font.word_spacing/1, Svg.color/1
• layout-aware transforms: Emerge.UI.scale/1, Emerge.UI.rotate/1
• paint-only transforms: Transform.move_x/1, Transform.move_y/1, Transform.rotate/1, Transform.scale/1, Transform.alpha/1

Other attrs, such as events, alignment, and font family/style/weight helpers, are not animatable.

Layout

Animation overlays are applied before measurement and layout each frame.

That means animated layout attrs such as width/1, height/1, padding/1, spacing/1, scale/1, and rotate/1 participate in relayout. The first keyframe also establishes the initial layout state before any animation time has elapsed.

Dimension transitions interpolate native resolved allocation, not fill weights. Related finite geometry owners keep their own clocks; an early finisher holds its allocation until their group can release together. Loops are not finite waiters. Text, images, scroll clipping and hit regions follow the real layout.

If native frame preparation fails, the last published layout and hit regions remain available. Repeated animation-only retries back off to a maximum 250ms delay; external updates and explicit retries are not throttled.