select-animation 1.2.4 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "select-animation",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "High-performance JavaScript animation engine for organic & fluid motion",
   "main": "select-animation.js",  
   "scripts": {
@@ -23,4 +23,4 @@
   ],
   "author": "Housseyn Cheriet",
   "license": "MIT"
-}
+}

package/readme.md

@@ -1,6 +1,17 @@
 
 # 🚀 Select-Animation
 
+[![npm version](https://img.shields.io/npm/v/select-animation.svg)](https://www.npmjs.com/package/select-animation)
+[![GitHub license](https://img.shields.io/github/license/housseynCheriet/Select-Animation.svg)](https://github.com/housseynCheriet/Select-Animation)
+
+A high-performance, lightweight JavaScript animation engine.
+
+**Support our project:** [selectjs.vercel.app](https://selectjs.vercel.app)
+**NPM Package:** [npmjs.com/package/select-animation](https://www.npmjs.com/package/select-animation)
+**Source Code:** [github.com/housseynCheriet/Select-Animation](https://github.com/housseynCheriet/Select-Animation)
+
+---
+
 ## **High‑Performance JavaScript Engine for Organic & Fluid Motion**
 
 **Select-Animation** is a lightweight yet powerful JavaScript animation engine built in pure JavaScript, with zero dependencies. Designed for developers who require **full control over timing, easing, looping, and DOM interactions**, it emphasizes **performance, mathematical precision, and flexibility**.
@@ -233,16 +244,7 @@ Experiment with **Select-Animation** and explore various examples in your browse
 
 This interactive playground allows you to tweak properties, easing types, and sequences in real-time.
 
----
-
-[![npm version](https://img.shields.io/npm/v/select-animation.svg)](https://www.npmjs.com/package/select-animation)
-[![GitHub license](https://img.shields.io/github/license/housseynCheriet/Select-Animation.svg)](https://github.com/housseynCheriet/Select-Animation)
-
-A high-performance, lightweight JavaScript animation engine.
 
-**Support our project:** [selectjs.vercel.app](https://selectjs.vercel.app)
-**NPM Package:** [npmjs.com/package/select-animation](https://www.npmjs.com/package/select-animation)
-**Source Code:** [github.com/housseynCheriet/Select-Animation](https://github.com/housseynCheriet/Select-Animation)
 
 ---
 

package/select-animation.js

@@ -117,54 +117,37 @@
         const definitions = arguments;
         const defsCopy = copyObj(definitions);
 
-        return function (targets, primaryParam, runtimeContext) {
-            let currentTargets, eventCheckResult, tmp, i, propIndex, fromItem, toItem, valFrom, valTo, t;
+        return function () {
+            let tmp, i, propIndex, fromItem, toItem, valFrom, valTo, t;
             let grouped = [];
-            let runtimeGrouped = [];
             let expectNextGroup = false;
             let staging = { color: {}, transform: {}, from: {}, to: {} };
 
+            // Process the definitions to map elements to their animation settings
             buildPlan();
 
             function buildPlan() {
-                if (targets !== undefined) {
-                    if (!Array.isArray(targets)) targets = [targets];
-                    runtimeGrouped = targets;
-                }
-
                 let secondPass = false;
 
                 for (let c = 0, total = definitions.length; c < total; c++) {
                     propIndex = 0;
+                    // If current item is an element or an array of elements
                     if (expectNextGroup || Array.isArray(defsCopy[c]) || isElement(defsCopy[c])) {
                         if (secondPass) {
                             Array.isArray(defsCopy[c]) || (defsCopy[c] = [defsCopy[c]]);
                             Array.prototype.push.apply(grouped, defsCopy[c]);
                         }
                         expectNextGroup = false;
-                    } else if (typeof defsCopy[c] === 'object' && defsCopy[c] !== null) {
+                    } 
+                    // If current item is a configuration object
+                    else if (typeof defsCopy[c] === 'object' && defsCopy[c] !== null) {
                         if (secondPass) {
-                            if (c === 0) {
-                                for (let u = 0; void 0 !== targets[u]; u++) {
-                                    if (typeof targets[u] !== "number") grouped.push(targets[u]);
-                                }
-                            }
-                            if (targets !== undefined) {
-                                for (let j = 0; void 0 !== runtimeGrouped[j]; j++) {
-                                    if (typeof runtimeGrouped[j] !== "number") {
-                                        eventCheckResult = checkValEvent(runtimeContext, primaryParam, currentTargets, runtimeGrouped[j + 1]);
-                                        if (eventCheckResult[0]) currentTargets = eventCheckResult[0];
-                                        bindEvent(runtimeGrouped[j], runner(grouped, definitions, defsCopy, c), eventCheckResult[1]);
-                                    }
-                                }
-                            } else {
-                                runner(grouped, definitions, defsCopy, c)();
-                            }
+                            // Execute the runner for the current group and config
+                            runner(grouped, definitions, defsCopy, c)();
                         } else {
                             expectNextGroup = false;
-                            const fromIsObject = typeof defsCopy[c].from === "object";
-                            const toIsObject = typeof defsCopy[c].to === "object";
-
+                            
+                            // Handle specialized animation types like vibration
                             if (defsCopy[c].typeAnimation === "vibration" && defsCopy[c].vibrationStep === undefined) {
                                 defsCopy[c].vibrationStep = 6;
                             } else {
@@ -175,20 +158,26 @@
                                 }
                             }
 
+                            // Set default loop behavior
                             if (defsCopy[c].boucle && defsCopy[c].boucleType === undefined) {
                                 defsCopy[c].boucleType = "return";
                             }
 
+                            // Organize properties and prepare "from" and "to" values
                             if (!defsCopy[c].callback &&
                                 (Array.isArray(defsCopy[c].property) || (defsCopy[c].property !== undefined && (defsCopy[c].property = [defsCopy[c].property])))) {
                                 
                                 defsCopy[c].property.forEach(function (propItem) {
+                                    const fromIsObject = typeof defsCopy[c].from === "object";
+                                    const toIsObject = typeof defsCopy[c].to === "object";
+
                                     if (!fromIsObject) valFrom = defsCopy[c].from;
                                     else fromItem = defsCopy[c]["from"][propIndex];
 
                                     if (!toIsObject) valTo = defsCopy[c].to;
                                     else toItem = defsCopy[c]["to"][propIndex];
 
+                                    // Handle complex properties (Colors and Transforms)
                                     if (typeof propItem === "object") {
                                         let propName = Object.keys(propItem)[0];
                                         if (!Array.isArray(propItem[propName])) propItem[propName] = [propItem[propName]];
@@ -204,6 +193,7 @@
                                                 if (propName.toLowerCase() === "transform") staging[propName][innerProp] = 0;
                                                 else staging.color[propName][innerProp] = 0;
 
+                                                // Parse specific sub-properties (like scale, rotate, or RGB channels)
                                                 if (fromIsObject) {
                                                     if (fromItem[propName] !== undefined) {
                                                         if (typeof fromItem[propName] === "number") {
@@ -220,6 +210,7 @@
                                                     staging["from"][propName][innerProp] = defsCopy[c].from;
                                                 }
 
+                                                // Repeat logic for "to" values
                                                 if (toIsObject) {
                                                     if (toItem[propName] !== undefined) {
                                                         if (typeof toItem[propName] === "number") {
@@ -240,6 +231,7 @@
                                             propIndex++;
                                         }
                                     } else {
+                                        // Handle simple numeric CSS properties (e.g., width, opacity)
                                         if (fromIsObject) {
                                             valFrom = staging["from"][propItem] = fromItem[propItem] !== undefined ? fromItem[propItem] : (fromItem !== undefined ? fromItem : valFrom);
                                         } else {
@@ -255,14 +247,19 @@
                                     }
                                 });
                             }
+                            // Save the processed plan into a store for runtime use
                             defsCopy[c].storeValueAnim = copyObj(staging);
                             staging = { color: {}, transform: {}, from: {}, to: {} };
                         }
+                        
+                        // Check if the next argument starts a new animation sequence
                         if (definitions[c + 1] !== undefined && (Array.isArray(definitions[c + 1]) || isElement(definitions[c + 1]))) {
                             expectNextGroup = true;
                             grouped = [];
                         }
                     }
+                    
+                    // Switch to second pass to execute the runners
                     if (c === total - 1 && !secondPass) {
                         expectNextGroup = false;
                         secondPass = true;
@@ -276,9 +273,11 @@
                 const declaredAnim = defsCopyLocal[configIndex].typeAnimation;
                 let alternateAnim = declaredAnim;
 
+                // Sanitize timing inputs
                 conf.timeline = !isNaN(Number(conf.timeline)) ? Number(conf.timeline) : 0;
                 conf.startafter = !isNaN(Number(conf.startafter)) ? Number(conf.startafter) : 0;
 
+                // Prepare looping and easing alternates
                 if (conf.boucle) {
                     conf.delay = !isNaN(Number(conf.delay)) ? Number(conf.delay) : undefined;
                     if (conf.boucleType === "returnRepeat" || conf.boucleType === "repeatReturn") {
@@ -291,6 +290,7 @@
                     let isPaused = false;
                     let pauseStart;
 
+                    // Initialize event-based pause/resume logic if configured
                     if (conf.pause && Array.isArray(conf.pause)) {
                         const eventCfg = conf.pause[1] || "e:click|false";
                         const parts = eventCfg.replace('e:', '').split('|');
@@ -315,6 +315,7 @@
 
                     const startedAt = Date.now();
 
+                    // Initialize state storage for each element in the group
                     group.forEach(function (el, idx) {
                         if (!el.storeTransform) el.storeTransform = copyObj(defsCopyLocal[configIndex].storeValueAnim.transform);
                         if (!el.storeColor) {
@@ -325,16 +326,19 @@
                             });
                         }
 
+                        // Start staggered animations if timeline offset exists
                         if (conf.timeline !== 0) {
                             frameRunner([el], idx, conf.timeline * idx + conf.startafter, conf.startafter);
                         }
                     });
 
+                    // Start simultaneous animations
                     if (conf.timeline === 0) {
                         frameRunner(group, 0, 0 + conf.startafter, conf.startafter);
                     }
 
                     function frameRunner(targetArray, idx, timeOffset, startAfter) {
+                        // Manage animation frame cycles
                         if (conf.animFram) cancelAnimationFrame(conf.animFram[idx]);
                         else conf.animFram = {};
 
@@ -346,6 +350,7 @@
                         let skipCounter;
                         const sv = iterConf.storeValueAnim;
 
+                        // The main animation loop using requestAnimationFrame
                         function loop() {
                             if (isPaused) {
                                 conf.animFram[idx] = requestAnimationFrame(loop);
@@ -357,6 +362,7 @@
                             const elapsed = Date.now() - (startedAt + timeOffset + pausedAccum);
 
                             if (elapsed >= 0) {
+                                // Logic for handling loops, delays, and reversing (yoyo) animations
                                 if (iterConf.boucle) {
                                     if (iterConf.delay !== undefined) {
                                         delay = iterConf.delay;
@@ -398,7 +404,9 @@
                                     iterConf.timeEasing = elapsed < iterConf.duration ? elapsed : iterConf.duration;
                                 }
 
+                                // Update properties if not in delay phase
                                 if (!iterConf.skipDelay || iterConf.skip) {
+                                    // Calculate ease factor (0 to 1)
                                     eased = Easing[iterConf.changetypeAnim][0](iterConf.timeEasing, 0, 1, iterConf.duration, iterConf, idx);
 
                                     if (iterConf.callback) {
@@ -406,6 +414,7 @@
                                             iterConf.callback(el, eased, iterConf, idx !== index ? idx : index);
                                         });
                                     } else {
+                                        // Apply styles: Transform, Color, or standard Numeric properties
                                         iterConf.property.forEach(function (prop) {
                                             css = "";
                                             let key = typeof prop === "string" ? prop : Object.keys(prop)[0];
@@ -444,6 +453,7 @@
                                 }
                             }
 
+                            // Continue the loop if animation is still active or looping
                             if (iterConf.boucle || elapsed < iterConf.duration) {
                                 conf.animFram[idx] = requestAnimationFrame(loop);
                             }