Raxol.Animation.Framework (Raxol v0.5.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 (target_path can be a property, e.g., [:opacity])
Raxol.Animation.Framework.create_animation(:fade_in, %{
  target_path: [:opacity], # Will be automatically scoped to the element's state
  duration: 300,
  easing: :ease_out_cubic,
  from: 0.0,
  to: 1.0
})

# Start the animation on an element
# The framework will update [:elements, "my_element_id", :opacity] in the state
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)

About target_path

When defining an animation, you can specify target_path as a single property (e.g., [:opacity]). When you start the animation for a specific element, the framework will automatically scope the path to that element:

  • If you pass element_id = "foo" and target_path = [:opacity], the animation will update [:elements, "foo", :opacity] in your state.
  • If you provide a fully qualified path (e.g., [:elements, "foo", :opacity]), it will be used as-is.

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.

Stops all animations and clears animation state. Used for test cleanup.

Stops a specific animation for an element.

Functions

apply_animations_to_state(state, user_preferences_pid \\ nil)

Update animations and apply their current values to the state.

Parameters

  • state - Current application state
  • user_preferences_pid - (Optional) The UserPreferences process pid or name for accessibility announcements

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
  • :target_path - Path within the state to animate. This can be a property (e.g., [:opacity]), in which case the framework will scope it to the element's state when starting the animation. If you provide a fully qualified path (e.g., [:elements, "my_element_id", :opacity]), it will be used as-is.

Examples

iex> AnimationFramework.create_animation(:fade_in, %{
...>   type: :fade,
...>   duration: 300,
...>   easing: :ease_out_cubic,
...>   from: 0.0,
...>   to: 1.0,
...>   direction: :in,
...>   target_path: [:opacity] # Will be scoped to the element when started
...> })
%{
  name: :fade_in,
  type: :fade,
  duration: 300,
  easing: :ease_out_cubic,
  from: 0.0,
  to: 1.0,
  direction: :in,
  target_path: [:opacity]
}

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 \\ %{}, user_preferences_pid \\ nil)

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?(user_preferences_pid \\ nil)

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

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
  • user_preferences_pid - (Optional) The UserPreferences process pid or name for accessibility announcements

Options

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

Path Scoping

If the animation's target_path is a property (e.g., [:opacity]), the framework will automatically scope it to the element's state (e.g., [:elements, element_id, :opacity]). If you provide a fully qualified path, it will be used as-is.

Examples

iex> AnimationFramework.start_animation(:fade_in, "search_button", %{}, user_preferences_pid)
:ok

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

stop()

Stops all animations and clears animation state. Used for test cleanup.

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