Raxol.Animation.Framework (Raxol v0.3.0)

View Source

Coordinates the lifecycle of animations within Raxol.

This module acts as the main entry point for creating, starting, stopping, and applying animations to the application state. It relies on supporting modules for specific concerns:

The framework automatically handles:

  • Timing and progress calculation.
  • Applying interpolated values to the application state via configured paths.
  • Managing animation completion and callbacks.
  • Adapting to reduced motion settings.

Usage

# Initialize the framework (typically done once on application start)
Raxol.Animation.Framework.init()

# Define an animation
Raxol.Animation.Framework.create_animation(:fade_in, %{
  target_path: [:opacity], # Path within state to animate
  duration: 300,
  easing: :ease_out_cubic,
  from: 0.0,
  to: 1.0
})

# Start the animation on an element
Raxol.Animation.Framework.start_animation(:fade_in, :my_element_id)

# In the application's update loop, apply animations to the state
updated_state = Raxol.Animation.Framework.apply_animations_to_state(current_state)

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)
  • :cognitive_accessibility - Start with cognitive accessibility (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

should_apply_cognitive_accessibility?()

should_reduce_motion?()

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