tiny-essentials 1.22.4 → 1.22.6

package/dist/v1/libs/TinyHtml.mjs

@@ -286,6 +286,90 @@ const __elemCollision = {
 class TinyHtml {
     /** @typedef {import('../basics/collision.mjs').ObjRect} ObjRect */
     static Utils = { ...TinyCollision };
+    /**
+     * Controls whether TinyHtml emits detailed debug output to the console.
+     * When enabled, helper methods print structured diagnostics for easier troubleshooting.
+     * @type {boolean}
+     */
+    static #elemDebug = false;
+    /**
+     * Gets whether debug output is enabled.
+     * @returns {boolean} True if debug output is enabled; otherwise, false.
+     */
+    static get elemDebug() {
+        return TinyHtml.#elemDebug;
+    }
+    /**
+     * Enables or disables debug output.
+     * @param {boolean} value True to enable debug output; false to disable.
+     * @throws {TypeError} Thrown if the provided value is not a boolean.
+     * @returns {void}
+     */
+    static set elemDebug(value) {
+        if (typeof value !== 'boolean')
+            throw new TypeError('Expected a boolean value for elemDebug');
+        TinyHtml.#elemDebug = value;
+    }
+    /**
+     * Logs a standardized debug error for element validation, including a console.table
+     * with the involved elements. Use this when an element argument is invalid, unexpected,
+     * or fails a guard/validation.
+     *
+     * The output includes:
+     *  - A concise error header
+     *  - A stack trace (when supported)
+     *  - A table of elements (index, typeof, constructor, summary, value)
+     *  - The specific problematic element, if provided
+     *
+     * @param {(ConstructorElValues | EventTarget | TinyElement | null)[]} elems
+     *        A list of elements participating in the operation (may include nulls).
+     * @param {ConstructorElValues | EventTarget | TinyElement | null} [elem]
+     *        The specific element that triggered the error, if available.
+     * @returns {void}
+     */
+    static _debugElemError(elems, elem) {
+        if (!TinyHtml.#elemDebug)
+            return;
+        const header = '[TinyHtml Debug] Element validation error';
+        console.groupCollapsed(`${header}${elem ? ' — details below' : ''}`);
+        console.error(header);
+        // Stack trace for call-site visibility
+        if (typeof Error !== 'undefined' && typeof Error.captureStackTrace === 'function') {
+            const err = new Error(header);
+            Error.captureStackTrace(err, TinyHtml._debugElemError);
+            console.error(err.stack);
+        }
+        else {
+            console.trace(header);
+        }
+        // Tabular overview of provided elements
+        if (Array.isArray(elems)) {
+            const rows = elems.map((el, index) => {
+                const typeOf = el === null ? 'null' : typeof el;
+                const ctor = el?.constructor?.name ?? (el === null ? 'null' : 'primitive');
+                const isDomEl = typeof Element !== 'undefined' && el instanceof Element;
+                const summary = isDomEl
+                    ? `${el.tagName?.toLowerCase?.() ?? 'element'}#${el.id || ''}.${String(el.className || '')
+                        .trim()
+                        .replace(/\s+/g, '.')}`
+                    : el && typeof el === 'object' && 'nodeType' in el
+                        ? `nodeType:${ /** @type {any} */(el).nodeType}`
+                        : '';
+                return { index, typeOf, constructor: ctor, summary, value: el };
+            });
+            console.table(rows);
+        }
+        else {
+            console.warn('[TinyHtml Debug] "elems" is not an array:', elems);
+        }
+        // Highlight the specific problematic element, if any
+        if (arguments.length > 1) {
+            console.error('[TinyHtml Debug] Problematic element:', elem);
+            if (elem && typeof elem === 'object')
+                console.dir(elem);
+        }
+        console.groupEnd();
+    }
     /**
      * Parse inline styles into an object.
      * @param {string} styleText
@@ -815,8 +899,10 @@ class TinyHtml {
         if (!(this.#el[index] instanceof Element) &&
             !(this.#el[index] instanceof Window) &&
             !(this.#el[index] instanceof Document) &&
-            !(this.#el[index] instanceof Text))
+            !(this.#el[index] instanceof Text)) {
+            TinyHtml._debugElemError([...this.#el], this.#el[index]);
             throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
+        }
         return this.#el[index];
     }
     /**
@@ -830,8 +916,10 @@ class TinyHtml {
         if (!this.#el.every((el) => el instanceof Element ||
             el instanceof Window ||
             el instanceof Document ||
-            el instanceof Text))
+            el instanceof Text)) {
+            TinyHtml._debugElemError([...this.#el]);
             throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
+        }
         return [...this.#el];
     }
     //////////////////////////////////////////////////////
@@ -860,8 +948,10 @@ class TinyHtml {
                         break;
                     }
                 }
-                if (!allowed)
+                if (!allowed) {
+                    TinyHtml._debugElemError([...item], result);
                     throw new Error(`[TinyHtml] Invalid element of the list "${elemName.join(',')}" in ${where}().`);
+                }
                 results.push(result);
                 return result;
             }));
@@ -888,8 +978,10 @@ class TinyHtml {
         const checkElement = (item) => {
             const elem = item[0];
             const result = elem instanceof TinyHtml ? elem._getElements(where) : [elem];
-            if (result.length > 1)
+            if (result.length > 1) {
+                TinyHtml._debugElemError([...item]);
                 throw new Error(`[TinyHtml] Invalid element amount in ${where}() (Received ${result.length}/1).`);
+            }
             let allowed = false;
             for (const TheTinyElement of TheTinyElements) {
                 if (result[0] instanceof TheTinyElement) {
@@ -901,14 +993,18 @@ class TinyHtml {
                 result[0] = null;
                 allowed = true;
             }
-            if (!allowed)
+            if (!allowed) {
+                TinyHtml._debugElemError([...item], result[0]);
                 throw new Error(`[TinyHtml] Invalid element of the list "${elemName.join(',')}" in ${where}().`);
+            }
             return result[0];
         };
         if (!Array.isArray(elems))
             return checkElement([elems]);
-        if (elems.length > 1)
+        if (elems.length > 1) {
+            TinyHtml._debugElemError([...elems]);
             throw new Error(`[TinyHtml] Invalid element amount in ${where}() (Received ${elems.length}/1).`);
+        }
         return checkElement(elems);
     }
     /**
@@ -5843,6 +5939,277 @@ class TinyHtml {
         const propName = typeof TinyHtml.attrFix[name] === 'string' ? TinyHtml.attrFix[name] : name;
         return propName;
     }
+    ////////////////////////////////////////////////////////////////////
+    /**
+     * Returns the BigInt value of an attribute.
+     * @param {TinyElement} el
+     * @param {string} name
+     * @returns {bigint|null}
+     */
+    static attrBigInt(el, name) {
+        const elem = TinyHtml._preElem(el, 'attrBigInt');
+        const val = elem.getAttribute(TinyHtml.getAttrName(name));
+        if (val == null)
+            return null;
+        try {
+            return BigInt(val);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Returns the BigInt value of an attribute.
+     * @param {string} name
+     * @returns {bigint|null}
+     */
+    attrBigInt(name) {
+        return TinyHtml.attrBigInt(this, name);
+    }
+    /**
+     * Set a BigInt attribute.
+     * @template {TinyElement|TinyElement[]} T
+     * @param {T} el
+     * @param {string} name
+     * @param {bigint} value
+     * @returns {T}
+     */
+    static setAttrBigInt(el, name, value) {
+        if (typeof value !== 'bigint')
+            throw new Error('Value is not a valid BigInt.');
+        return TinyHtml.setAttr(el, name, value.toString());
+    }
+    /**
+     * Set a BigInt attribute.
+     * @param {string} name
+     * @param {bigint} value
+     * @returns {this}
+     */
+    setAttrBigInt(name, value) {
+        return TinyHtml.setAttrBigInt(this, name, value);
+    }
+    /**
+     * Returns the Date value of an attribute.
+     * @param {TinyElement} el
+     * @param {string} name
+     * @returns {Date|null}
+     */
+    static attrDate(el, name) {
+        const elem = TinyHtml._preElem(el, 'attrDate');
+        const val = elem.getAttribute(TinyHtml.getAttrName(name));
+        if (!val)
+            return null;
+        const d = new Date(val);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    /**
+     * Returns the Date value of an attribute.
+     * @param {string} name
+     * @returns {Date|null}
+     */
+    attrDate(name) {
+        return TinyHtml.attrDate(this, name);
+    }
+    /**
+     * Set a Date attribute.
+     * @template {TinyElement|TinyElement[]} T
+     * @param {T} el
+     * @param {string} name
+     * @param {Date} value
+     * @returns {T}
+     */
+    static setAttrDate(el, name, value) {
+        if (!(value instanceof Date) || Number.isNaN(value.getTime()))
+            throw new Error('Value is not a valid Date.');
+        return TinyHtml.setAttr(el, name, value.toISOString());
+    }
+    /**
+     * Set a Date attribute.
+     * @param {string} name
+     * @param {Date} value
+     * @returns {this}
+     */
+    setAttrDate(name, value) {
+        return TinyHtml.setAttrDate(this, name, value);
+    }
+    /**
+     * Returns the JSON value of an attribute.
+     * @param {TinyElement} el
+     * @param {string} name
+     * @returns {any|null}
+     */
+    static attrJson(el, name) {
+        const elem = TinyHtml._preElem(el, 'attrJson');
+        const val = elem.getAttribute(TinyHtml.getAttrName(name));
+        if (!val)
+            return null;
+        try {
+            return JSON.parse(val);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Returns the JSON value of an attribute.
+     * @param {string} name
+     * @returns {any|null}
+     */
+    attrJson(name) {
+        return TinyHtml.attrJson(this, name);
+    }
+    /**
+     * Set a JSON attribute.
+     * @template {TinyElement|TinyElement[]} T
+     * @param {T} el
+     * @param {string} name
+     * @param {any} value
+     * @param {(this: any, key: string, value: any) => any} [replacer]
+     * @param {number|string} [space]
+     * @returns {T}
+     */
+    static setAttrJson(el, name, value, replacer, space) {
+        const data = JSON.stringify(value, replacer, space);
+        return TinyHtml.setAttr(el, name, data);
+    }
+    /**
+     * Set a JSON attribute.
+     * @param {string} name
+     * @param {any} value
+     * @param {(this: any, key: string, value: any) => any} [replacer]
+     * @param {number|string} [space]
+     * @returns {this}
+     */
+    setAttrJson(name, value, replacer, space) {
+        return TinyHtml.setAttrJson(this, name, value, replacer, space);
+    }
+    /**
+     * Returns the number value of an attribute.
+     * @param {TinyElement} el
+     * @param {string} name
+     * @returns {number|null}
+     */
+    static attrNumber(el, name) {
+        const elem = TinyHtml._preElem(el, 'attrNumber');
+        const val = elem.getAttribute(TinyHtml.getAttrName(name));
+        return val != null ? parseFloat(val) : null;
+    }
+    /**
+     * Returns the number value of an attribute.
+     * @param {string} name
+     * @returns {number|null}
+     */
+    attrNumber(name) {
+        return TinyHtml.attrNumber(this, name);
+    }
+    /**
+     * Set a number attribute.
+     * @template {TinyElement|TinyElement[]} T
+     * @param {T} el
+     * @param {string} name
+     * @param {number} value
+     * @returns {T}
+     */
+    static setAttrNumber(el, name, value) {
+        if (typeof value !== 'number')
+            throw new Error('Value is not a valid number.');
+        return TinyHtml.setAttr(el, name, value.toString());
+    }
+    /**
+     * Set a number attribute.
+     * @param {string} name
+     * @param {number} value
+     * @returns {this}
+     */
+    setAttrNumber(name, value) {
+        return TinyHtml.setAttrNumber(this, name, value);
+    }
+    /**
+     * Returns the boolean value of an attribute.
+     * @param {TinyElement} el
+     * @param {string} name
+     * @returns {boolean|null}
+     */
+    static attrBoolean(el, name) {
+        const elem = TinyHtml._preElem(el, 'attrBoolean');
+        const val = elem.getAttribute(TinyHtml.getAttrName(name));
+        if (val === null)
+            return null;
+        if (val !== 'true' && val !== 'false')
+            return null;
+        return /^true$/i.test(val);
+    }
+    /**
+     * Returns the boolean value of an attribute.
+     * @param {string} name
+     * @returns {boolean|null}
+     */
+    attrBoolean(name) {
+        return TinyHtml.attrBoolean(this, name);
+    }
+    /**
+     * Set a boolean attribute.
+     * @template {TinyElement|TinyElement[]} T
+     * @param {T} el
+     * @param {string} name
+     * @param {boolean} value
+     * @returns {T}
+     */
+    static setAttrBoolean(el, name, value) {
+        if (typeof value !== 'boolean')
+            throw new Error('Value is not a valid boolean.');
+        return TinyHtml.setAttr(el, name, value.toString());
+    }
+    /**
+     * Set a boolean attribute.
+     * @param {string} name
+     * @param {boolean} value
+     * @returns {this}
+     */
+    setAttrBoolean(name, value) {
+        return TinyHtml.setAttrBoolean(this, name, value);
+    }
+    /**
+     * Returns the string value of an attribute.
+     * @param {TinyElement} el
+     * @param {string} name
+     * @returns {string|null}
+     */
+    static attrString(el, name) {
+        const elem = TinyHtml._preElem(el, 'attrString');
+        const value = elem.getAttribute(TinyHtml.getAttrName(name));
+        return typeof value === 'string' ? value : null;
+    }
+    /**
+     * Returns the string value of an attribute.
+     * @param {string} name
+     * @returns {string|null}
+     */
+    attrString(name) {
+        return TinyHtml.attrString(this, name);
+    }
+    /**
+     * Set a string attribute.
+     * @template {TinyElement|TinyElement[]} T
+     * @param {T} el
+     * @param {string} name
+     * @param {string} value
+     * @returns {T}
+     */
+    static setAttrString(el, name, value) {
+        if (typeof value !== 'string')
+            throw new Error('Value is not a valid string.');
+        return TinyHtml.setAttr(el, name, value);
+    }
+    /**
+     * Set a string attribute.
+     * @param {string} name
+     * @param {string} value
+     * @returns {this}
+     */
+    setAttrString(name, value) {
+        return TinyHtml.setAttrString(this, name, value);
+    }
     /**
      * Get an attribute on an element.
      * @param {TinyElement} el
@@ -5867,43 +6234,37 @@ class TinyHtml {
      * Set one or multiple attributes on an element.
      * @template {TinyElement|TinyElement[]} T
      * @param {T} el - Target element(s).
-     * @param {string|Record<string, string|null>} name - Attribute name or an object of attributes.
-     * @param {string|number|null} [value=null] - Attribute value (ignored if "name" is an object).
+     * @param {string|Record<string, any>} name - Attribute name or an object of attributes.
+     * @param {any} [value=null] - Attribute value (ignored if "name" is an object).
      * @returns {T}
      */
     static setAttr(el, name, value = null) {
         const elems = TinyHtml._preElems(el, 'setAttr');
         // Multiple attributes at once
         if (typeof name === 'object' && name !== null) {
-            Object.entries(name).forEach(([attr, val]) => {
-                if (val !== null && typeof val !== 'string' && typeof val !== 'number')
-                    throw new TypeError(`The value for "${attr}" must be a string/number or null.`);
-                elems.forEach((elem) => {
-                    if (val === null)
-                        elem.removeAttribute(TinyHtml.getAttrName(attr));
-                    else
-                        elem.setAttribute(TinyHtml.getAttrName(attr), val);
-                });
-            });
+            Object.entries(name).forEach(([attr, val]) => elems.forEach((elem) => {
+                if (val === null)
+                    elem.removeAttribute(TinyHtml.getAttrName(attr));
+                else
+                    elem.setAttribute(TinyHtml.getAttrName(attr), String(val));
+            }));
             return el;
         }
         // Single attribute
         if (typeof name !== 'string')
             throw new TypeError('The "name" must be a string.');
-        if (value !== null && typeof value !== 'string')
-            throw new TypeError('The "value" must be a string.');
         elems.forEach((elem) => {
             if (value === null)
                 elem.removeAttribute(TinyHtml.getAttrName(name));
             else
-                elem.setAttribute(TinyHtml.getAttrName(name), value);
+                elem.setAttribute(TinyHtml.getAttrName(name), String(value));
         });
         return el;
     }
     /**
      * Set one or multiple attributes on an element.
-     * @param {string|Record<string, string|null>} name - Attribute name or an object of attributes.
-     * @param {string|number|null} [value=null] - Attribute value (ignored if "name" is an object).
+     * @param {string|Record<string, any>} name - Attribute name or an object of attributes.
+     * @param {any} [value=null] - Attribute value (ignored if "name" is an object).
      * @returns {this}
      */
     setAttr(name, value) {

package/docs/v1/libs/TinyHtml.md

@@ -2076,6 +2076,42 @@ element.removeAttr("data-test");       // Remove
 element.hasAttr("id");                 // Check
 ```
 
+```js
+element.attrBigInt("example");             // Get
+element.setAttrBigInt("example", 10n);     // Set
+element.setAttrBigInt({ "example": 10n }); // Set
+```
+
+```js
+element.attrDate("example");                    // Get
+element.setAttrDate("example", new Date());     // Set
+element.setAttrDate({ "example": new Date() }); // Set
+```
+
+```js
+element.attrJson("example");                           // Get
+element.setAttrJson("example", { pudding: true });     // Set
+element.setAttrJson({ "example": { pudding: true } }); // Set
+```
+
+```js
+element.attrNumber("example");           // Get
+element.setAttrNumber("example", 1);     // Set
+element.setAttrNumber({ "example": 1 }); // Set
+```
+
+```js
+element.attrBoolean("example");              // Get
+element.setAttrBoolean("example", true);     // Set
+element.setAttrBoolean({ "example": true }); // Set
+```
+
+```js
+element.attrString("example");                   // Get
+element.setAttrString("example", "pudding");     // Set
+element.setAttrString({ "example": "pudding" }); // Set
+```
+
 Works on both single and multiple elements (static or instance).
 Safe and type-checked — throws if misuse is detected.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.22.4",
+  "version": "1.22.6",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",