Professional Documentation for SelectJs Animation Engine

Introduction

In the world of web development, movements and transitions are an essential part of enhancing the user experience, making interfaces more lively and interactive. High-performance animations require execution precision, customization flexibility, and ease of use. This is where the SelectJs library comes in as an advanced solution for creating smooth, natural, and flexible animations on DOM elements, with full support for interactions and events.

Library Overview

SelectJs is an open-source JavaScript library designed to provide a high-performance animation engine based on best coding practices. It aims to empower developers to design complex and smooth animations without the need to write extensive code, while ensuring compatibility with all browsers, including older ones.

Advanced Features

• Dynamic timing with delays and timelines.
• Deep copy for data safety.
• Automatic cleanup of resources.

Why choose SelectJs?

• High-quality, smooth, and realistic animations.
• Flexible for simple or complex movements.
• Easy-to-use API.
• Full interaction support.
• Compatible with all major browsers, including older ones.

Core Features of the Library

Feature	Description
High Performance	Relies on requestAnimationFrame for smooth updates.
High Flexibility	Supports animating CSS properties, Transforms, colors, and compound values.
Full Customization	Control over duration, easing, looping, delays, and events.
Dynamic Interactivity	Links animations to user events like clicks and scrolls.
Data Protection	Uses deep cloning to ensure data integrity during modifications.
Easing Functions	Wide range of easing options for natural movements.
Ease of Use	Simple API with support for multiple components.

Library Components and Functions

1. Element Selection (selectDom)

• Function: Select DOM elements via CSS and return an array.
• Usage:

  const elements = selectDom('.my-class', '#my-id');

• Purpose: Simplifies element targeting for animations.

2. Animation Setup (animate)

• Function: Create and customize animations with properties, timing, easing, and callbacks.
• Usage Example:

  const move = animate(elements, {
    property: 'left',
    from: '0px',
    to: '300px',
    duration: 1000,
    ease: 'cubic-inout',
    callback: () => { console.log('Animation Ended'); }
  });
  move(); // To start the animation

• Core Properties:
  • property
  • from & to
  • duration
  • ease
  • delay
  • loop
  • callback
• Note: Multiple definitions can be synchronized or sequenced.

3. Supported Properties & Colors

• Supported Properties: width, height, opacity, margin, padding, translateX, translateY, rotate, scale, color, backgroundColor, borderColor, etc.
• Colors: Support RGBA, gradients, smooth color transitions.
• Compound Properties: Animate multiple properties together for complex effects.

4. Timing & Loop Control

• Duration: Animation length in ms.
• Delay: Start delay in ms.
• Looping: Infinite or specific repeats with options like 'return', 'returnRepeat', 'infinite'.
• Reverse: Play in reverse or alternate direction.

5. Interactive Features

• Link animations to user events:
  • Pause on click
  • Resume on mouseup
  • Trigger on specific events
• Example:

  animate(element, {
    property: 'opacity',
    from: 0,
    to: 1,
    duration: 500,
    pause: ['.button', 'e:click|true']
  });

6. Easing Functions

• Options include: linear, quadratic, cubic, quart, quint, sine, expo, bounce, elastic, back, vibration, cubicBezier.
• Usage: ease: 'bounce'

7. Looping Modes (boucleType)

This property controls how animations loop. The four main modes are:

1. return:
   Plays from start to end, then immediately jumps back to start, repeating endlessly.
2. repeat:
   Plays from start to end, then jumps back to start, repeating.
3. returnRepeat:
   Plays forward, then reverses back (ping-pong), then repeats.
4. repeatReturn:
   Repeats forward, then jumps back to start.

animate(element, {
  property: 'left',
  from: '0px',
  to: '300px',
  duration: 1000,
  boucleType: 'return' // or 'repeat', 'returnRepeat', 'repeatReturn'
});

8. Event-Based Control

Control animations via user interactions:

pause: ['.element', 'e:click|true']

Understanding Looping Modes: The Four boucleType Cases

In configuring animations, boucleType controls how the animation repeats. The four main modes are:

1. return:
   Plays from start to end, then jumps immediately back to start, creating a continuous loop.
2. repeat:
   Similar to 'return' but may involve different behaviors for specific implementations.
3. returnRepeat:
   Plays forward, then reverses back (ping-pong), then repeats.
4. repeatReturn:
   Repeats forward, then jumps back to start, then repeats again.

Example usage:

animate(element, {
  property: 'left',
  from: '0px',
  to: '300px',
  duration: 1000,
  boucleType: 'return' // or 'repeat', 'returnRepeat', 'repeatReturn'
});