select-animation 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "select-animation",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "High-performance JavaScript animation engine for organic & fluid motion",
   "main": "select-animation.js",  
   "scripts": {

package/select-animation.js

@@ -100,13 +100,37 @@
     // Returns flat array of matched elements given one or more selectors
     // Usage: select('.class', '#id')
     // -----------------------------
-    const selectDom = function(...selectors) {
-        const all = [];
-        selectors.forEach(selector => {
-            const nodeList = document.querySelectorAll(selector);
-            all.push(...nodeList);
-        });
-        return all;
+    // --- Enhanced DOM Selection Utility with Explicit Error Reporting ---
+    const selectDom = function (selector) {
+        // 1. Check if the input is a DOM element directly
+        if (isElement(selector)) return [selector];
+
+        // 2. Handle string selectors (e.g., ".class", "#id")
+        if (typeof selector === "string") {
+            const nodes = document.querySelectorAll(selector);
+            if (nodes.length === 0) {
+                // Warning if the selector is valid string but matches nothing
+                console.warn(`Select-Animation: No elements found matching the selector "${selector}".`);
+            }
+            return Array.from(nodes);
+        }
+
+        // 3. Handle arrays or collections
+        if (Array.isArray(selector) || (selector && typeof selector.length === "number")) {
+            return Array.from(selector).filter(isElement);
+        }
+
+        // 4. CRITICAL: Handle invalid types (like numbers, null, undefined)
+        if (selector !== undefined && selector !== null) {
+            // Throwing a console error to stop the developer and force a fix
+            console.error(
+                `Select-Animation ERROR: Invalid input passed to selectDom().\n` +
+                `Expected: String (selector), HTMLElement, or Array.\n` +
+                `Received: ${typeof selector} (${selector})`
+            );
+        }
+
+        return [];
     };
 
     // -----------------------------
@@ -139,49 +163,65 @@
                         }
                         expectNextGroup = false;
                     } 
-                    // If current item is a configuration object
+                    // --- Handle Configuration Object with Validation ---
                     else if (typeof defsCopy[c] === 'object' && defsCopy[c] !== null) {
                         if (secondPass) {
-                            // Execute the runner for the current group and config
+                            // Execute the animation runner for the current group
                             runner(grouped, definitions, defsCopy, c)();
                         } else {
                             expectNextGroup = false;
+
+                            // 1. Validate Duration and Animation Type
+                            defsCopy[c].duration = (typeof defsCopy[c].duration === 'number' && defsCopy[c].duration > 0) ? defsCopy[c].duration : 1000;
                             
-                            // Handle specialized animation types like vibration
-                            if (defsCopy[c].typeAnimation === "vibration" && defsCopy[c].vibrationStep === undefined) {
+                            let requestedType = defsCopy[c].typeAnimation;
+
+                            if (requestedType === "vibration" && defsCopy[c].vibrationStep === undefined) {
                                 defsCopy[c].vibrationStep = 6;
-                            } else {
-                                t = getNumber(defsCopy[c].typeAnimation);
+                            } else if (requestedType) {
+                                t = getNumber(requestedType);
                                 if (t && t.length === 4) {
                                     defsCopy[c].cubicbezier = t;
                                     defsCopy[c].typeAnimation = "cubicbezier";
+                                } else {
+                                    // STOP EXECUTION: If easing is not found, do not fall back to linear
+                                    if (requestedType !== "linear" && requestedType !== "vibration" && requestedType !== "cubicbezier" && (!Easing || !Easing[requestedType])) {
+                                        // Use Error instead of warn to make it impossible to ignore
+                                        throw new Error(`Select-Animation ERROR: The easing function "${requestedType}" does not exist. Please check your spelling or definitions.`);
+                                    }
                                 }
                             }
-
-                            // 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 &&
+                            
+                            // Double-check if the animation type is valid before processing
+                            if (!defsCopy[c].typeAnimation) return;
+
+                            // 2. Helper to sanitize input values (convert "100px" to 100)
+                            const parseVal = (v) => {
+                                if (typeof v === "number") return v;
+                                let p = parseFloat(v);
+                                return isNaN(p) ? 0 : p;
+                            };
+
+                            // Process 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];
+                                    // Safely extract from/to values based on their types
+                                    if (!fromIsObject) valFrom = parseVal(defsCopy[c].from);
+                                    else fromItem = defsCopy[c]["from"][propIndex] || 0;
 
-                                    if (!toIsObject) valTo = defsCopy[c].to;
-                                    else toItem = defsCopy[c]["to"][propIndex];
+                                    if (!toIsObject) valTo = parseVal(defsCopy[c].to);
+                                    else toItem = defsCopy[c]["to"][propIndex] || 0;
 
-                                    // 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]];
 
+                                        // Handle Colors and Transform objects
                                         if ((propName.toLowerCase().indexOf("color") !== -1 && (staging.color[propName] = COLOR_PROPERTIES[propName])) ||
                                             propName.toLowerCase().indexOf("transform") !== -1) {
                                             
@@ -193,66 +233,55 @@
                                                 if (propName.toLowerCase() === "transform") staging[propName][innerProp] = 0;
                                                 else staging.color[propName][innerProp] = 0;
 
-                                                // Parse specific sub-properties (like scale, rotate, or RGB channels)
+                                                // Validate and assign nested properties
                                                 if (fromIsObject) {
-                                                    if (fromItem[propName] !== undefined) {
-                                                        if (typeof fromItem[propName] === "number") {
-                                                            valFrom = staging["from"][propName][innerProp] = fromItem[propName];
-                                                        } else if (Array.isArray(fromItem[propName])) {
-                                                            valFrom = staging["from"][propName][innerProp] = fromItem[propName][inner] !== undefined ? fromItem[propName][inner] : valFrom;
-                                                        } else if (fromItem[propName][innerProp] !== undefined) {
-                                                            valFrom = staging["from"][propName][innerProp] = fromItem[propName][innerProp];
-                                                        }
-                                                    } else {
-                                                        staging["from"][propName][innerProp] = valFrom;
-                                                    }
+                                                    let raw = (fromItem[propName] !== undefined) ? (Array.isArray(fromItem[propName]) ? fromItem[propName][inner] : fromItem[propName][innerProp]) : valFrom;
+                                                    staging["from"][propName][innerProp] = parseVal(raw);
                                                 } else {
-                                                    staging["from"][propName][innerProp] = defsCopy[c].from;
+                                                    staging["from"][propName][innerProp] = parseVal(defsCopy[c].from);
                                                 }
 
-                                                // Repeat logic for "to" values
                                                 if (toIsObject) {
-                                                    if (toItem[propName] !== undefined) {
-                                                        if (typeof toItem[propName] === "number") {
-                                                            valTo = staging["to"][propName][innerProp] = toItem[propName];
-                                                        } else if (Array.isArray(toItem[propName])) {
-                                                            valTo = staging["to"][propName][innerProp] = toItem[propName][inner] !== undefined ? toItem[propName][inner] : valTo;
-                                                        } else if (toItem[propName][innerProp] !== undefined) {
-                                                            valTo = staging["to"][propName][innerProp] = toItem[propName][innerProp];
-                                                        }
-                                                    } else {
-                                                        staging["to"][propName][innerProp] = valTo;
-                                                    }
+                                                    let raw = (toItem[propName] !== undefined) ? (Array.isArray(toItem[propName]) ? toItem[propName][inner] : toItem[propName][innerProp]) : valTo;
+                                                    staging["to"][propName][innerProp] = parseVal(raw);
                                                 } else {
-                                                    staging["to"][propName][innerProp] = defsCopy[c].to;
+                                                    staging["to"][propName][innerProp] = parseVal(defsCopy[c].to);
                                                 }
                                                 inner++;
                                             });
                                             propIndex++;
                                         }
                                     } else {
-                                        // Handle simple numeric CSS properties (e.g., width, opacity)
+                                        // Handle simple numeric CSS properties (width, height, etc.)
                                         if (fromIsObject) {
-                                            valFrom = staging["from"][propItem] = fromItem[propItem] !== undefined ? fromItem[propItem] : (fromItem !== undefined ? fromItem : valFrom);
+                                            let raw = fromItem[propItem] !== undefined ? fromItem[propItem] : (fromItem !== undefined ? fromItem : valFrom);
+                                            staging["from"][propItem] = parseVal(raw);
                                         } else {
-                                            staging["from"][propItem] = defsCopy[c].from;
+                                            staging["from"][propItem] = parseVal(defsCopy[c].from);
                                         }
 
                                         if (toIsObject) {
-                                            valTo = staging["to"][propItem] = toItem[propItem] !== undefined ? toItem[propItem] : (toItem !== undefined ? toItem : valTo);
+                                            let raw = toItem[propItem] !== undefined ? toItem[propItem] : (toItem !== undefined ? toItem : valTo);
+                                            staging["to"][propItem] = parseVal(raw);
                                         } else {
-                                            staging["to"][propItem] = defsCopy[c].to;
+                                            staging["to"][propItem] = parseVal(defsCopy[c].to);
                                         }
                                         propIndex++;
                                     }
                                 });
                             }
-                            // Save the processed plan into a store for runtime use
+
+                            // 3. Callback Safety Validation
+                            // Ensure hooks are actual functions to prevent execution errors
+                            if (defsCopy[c].onStep && typeof defsCopy[c].onStep !== 'function') defsCopy[c].onStep = null;
+                            if (defsCopy[c].onComplete && typeof defsCopy[c].onComplete !== 'function') defsCopy[c].onComplete = null;
+
+                            // Finalize staging data and store it
                             defsCopy[c].storeValueAnim = copyObj(staging);
                             staging = { color: {}, transform: {}, from: {}, to: {} };
                         }
-                        
-                        // Check if the next argument starts a new animation sequence
+
+                        // Determine if the next item starts a new sequence group
                         if (definitions[c + 1] !== undefined && (Array.isArray(definitions[c + 1]) || isElement(definitions[c + 1]))) {
                             expectNextGroup = true;
                             grouped = [];
@@ -767,8 +796,17 @@
         else return el.style[cssprop];
     }
 
+    // --- Robust DOM Element Validation ---
     function isElement(element) {
-        return element instanceof Element || element instanceof HTMLDocument;
+        try {
+            // Check for standard DOM Element or HTMLDocument
+            return element instanceof Element || element instanceof HTMLDocument;
+        } catch (e) {
+            // Fallback for environments where Element is not defined
+            return (typeof element === "object") && 
+                   (element.nodeType === 1) && 
+                   (typeof element.nodeName === "string");
+        }
     }
 
     const copyObj = function(obj) {