Raxol.Animation.Helpers (Raxol v2.6.0)

View DSL helpers for attaching animation hints to elements.

These are pure functions that attach metadata -- they do not start server-side animations. Starting animations is done in update/2 via Raxol.Animation.Framework.start_animation/3.

Usage

import Raxol.Animation.Helpers

def view(model) do
  box(id: "panel", style: %{opacity: model.panel_opacity})
  |> animate(property: :opacity, to: 1.0, duration: 300)
end

Summary

Functions

animate(element, opts)

Attaches an animation hint to a view element.

border_beam(element, opts \\ [])

Attaches a border beam animation hint to an element.

sequence(element, animation_opts_list)

Chains multiple animations on a single element sequentially.

stagger(elements, opts)

Applies the same animation hint to a list of elements with staggered delays.

Functions

animate(element, opts)

@spec animate(
  map(),
  keyword()
) :: map()

Attaches an animation hint to a view element.

The hint describes the animation shape so surface renderers can optionally accelerate (e.g., CSS transitions in LiveView).

Options

:property - (required) The property being animated (:opacity, :color, :bg, :width, :height, :transform)
:from - Starting value
:to - Target value
:duration - Duration in milliseconds (default: 300)
:easing - Easing function atom (default: :ease_out_cubic)
:delay - Delay in milliseconds (default: 0)

Examples

box(id: "card")
|> animate(property: :opacity, from: 0.0, to: 1.0, duration: 500)

text("Hello")
|> animate(property: :color, to: :cyan, easing: :ease_in_out_cubic)
|> animate(property: :opacity, to: 1.0, duration: 200)

border_beam(element, opts \\ [])

@spec border_beam(
  map(),
  keyword()
) :: map()

Attaches a border beam animation hint to an element.

The beam creates an animated glow that orbits the element's border. Surfaces handle it differently: terminal computes frames server-side, LiveView generates CSS conic-gradient + mask animations, MCP includes the hint in structured screenshots.

Options

:variant - Color variant: :colorful (default), :mono, :ocean, :sunset
:size - Size preset: :full (default), :compact, :line
:strength - Effect intensity 0.0-1.0 (default: 0.8)
:duration - Orbit duration in ms (default: 2000)
:brightness - Glow brightness multiplier (default: 1.3, LiveView only)
:saturation - Color saturation multiplier (default: 1.2, LiveView only)
:hue_range - Hue rotation degrees (default: 30, LiveView only)
:active - Whether the beam is running (default: true)
:static_colors - Disable color cycling (default: false)

Examples

panel(id: "status", border: :rounded)
|> border_beam(variant: :ocean, duration: 2000)

panel(id: "card", border: :single)
|> border_beam(variant: :sunset, strength: 0.6, size: :compact)

sequence(element, animation_opts_list)

@spec sequence(map(), [keyword()]) :: map()

Chains multiple animations on a single element sequentially.

Each animation's delay is computed from the cumulative duration of preceding animations, so they play one after another.

Examples

box(id: "card", style: %{opacity: 0})
|> sequence([
  [property: :opacity, to: 1.0, duration: 300],
  [property: :bg, to: :cyan, duration: 200],
  [property: :width, to: 40, duration: 400]
])
# opacity: delay 0, bg: delay 300, width: delay 500

stagger(elements, opts)

@spec stagger(
  [map()],
  keyword()
) :: [map()]

Applies the same animation hint to a list of elements with staggered delays.

Each element gets the same animation but with an incrementing delay_ms offset, creating an entrance cascade effect.

Options

All options from animate/2 plus:

:offset - Delay between each element in milliseconds (default: 50)

Examples

boxes = [
  box(id: "a", style: %{opacity: 0}),
  box(id: "b", style: %{opacity: 0}),
  box(id: "c", style: %{opacity: 0})
]

stagger(boxes, property: :opacity, to: 1.0, duration: 300, offset: 100)
# a: delay 0ms, b: delay 100ms, c: delay 200ms