Raxol.Animation.Framework (Raxol v0.2.0)

View Source

A general-purpose animation framework for Raxol terminal UI applications.

This module provides a comprehensive animation system that:

  • Supports various animation types (easing, physics-based, keyframes)
  • Respects reduced motion accessibility settings
  • Provides smooth transitions between UI states
  • Offers standard animation patterns for common interactions
  • Manages animation timing and rendering

The framework automatically adapts to user preferences for reduced motion and will provide alternative non-animated transitions when needed.

Usage

# Initialize the animation framework
AnimationFramework.init()

# Create a simple animation
animation = AnimationFramework.create_animation(:fade_in, %{
  duration: 300,
  easing: :ease_out_cubic
})

# Start the animation
AnimationFramework.start_animation(animation, :element_id)

# Update state with animation progress
updated_state = AnimationFramework.apply_animation(state, now)

Summary

Functions

Update animations and apply their current values to the state.

Create a new animation.

Gets the current value and completion status of an animation instance.

Initialize the animation framework.

Start an animation for a specific element.

Stops a specific animation for an element.

Functions

apply_animations_to_state(state)

Update animations and apply their current values to the state.

Parameters

  • state - Current application state

Returns

Updated state with animation values applied.

create_animation(name, params)

Create a new animation.

Parameters

  • name - Unique identifier for the animation
  • params - Animation parameters

Options

  • :type - Animation type (:fade, :slide, :scale, :color, :generic)
  • :duration - Duration in milliseconds
  • :easing - Easing function name
  • :from - Starting value
  • :to - Ending value
  • :direction - Animation direction (:in, :out)
  • :announce_to_screen_reader - Whether to announce to screen readers
  • :description - Description for screen reader announcements

Examples

iex> AnimationFramework.create_animation(:fade_in, %{
...>   type: :fade,
...>   duration: 300,
...>   easing: :ease_out_cubic,
...>   from: 0.0,
...>   to: 1.0,
...>   direction: :in
...> })
%{
  name: :fade_in,
  type: :fade,
  duration: 300,
  easing: :ease_out_cubic,
  from: 0.0,
  to: 1.0,
  direction: :in
}

get_current_value(animation_name, element_id)

Gets the current value and completion status of an animation instance.

Parameters

  • animation_name - The name of the animation
  • element_id - Identifier for the element being animated

Returns

  • {value, done?} - A tuple with the current animation value and a boolean indicating if it's finished.
  • :not_found - If the animation instance is not active.

Examples

iex> AnimationFramework.get_current_value(:fade_in, "search_button")
{0.5, false}

init(opts \\ %{})

Initialize the animation framework.

This sets up the necessary state for tracking animations and integrates with accessibility settings.

Options

  • :reduced_motion - Start with reduced motion (default: from accessibility settings)
  • :default_duration - Default animation duration in milliseconds (default: 300)
  • :frame_ms - Frame duration in milliseconds (default: 33)

Examples

iex> AnimationFramework.init()
:ok

iex> AnimationFramework.init(reduced_motion: true)
:ok

start_animation(animation_name, element_id, opts \\ %{})

Start an animation for a specific element.

Parameters

  • animation_name - The name of the animation to start
  • element_id - Identifier for the element being animated
  • opts - Additional options

Options

  • :on_complete - Function to call when animation completes
  • :context - Additional context for the animation

Examples

iex> AnimationFramework.start_animation(:fade_in, "search_button")
:ok

iex> AnimationFramework.start_animation(:slide_in, "panel", on_complete: &handle_complete/1)
:ok

stop_animation(animation_name, element_id)

Stops a specific animation for an element.

Parameters

  • animation_name - The name of the animation to stop
  • element_id - Identifier for the element being animated

Examples

iex> AnimationFramework.stop_animation(:fade_in, "search_button")
:ok