tiny-essentials 1.22.3 → 1.22.5

package/dist/v1/libs/TinyHtml.cjs

@@ -663,7 +663,7 @@ class TinyHtml {
    * ```
    *
    * @param {string} tagName - The HTML tag name (e.g., 'div', 'span', 'button').
-   * @param {Record<string, string|null>} [attrs] - Optional key-value pairs representing HTML attributes.
+   * @param {Record<string, string|number|null>} [attrs] - Optional key-value pairs representing HTML attributes.
    *                                                If the value is `null`, the attribute will still be set with an empty value.
    * @returns {TinyHtml<HTMLElement>} - A new instance of TinyHtml representing the created element.
    * @throws {TypeError} - If `tagName` is not a string, or `attrs` is not a plain object when defined.
@@ -859,13 +859,22 @@ class TinyHtml {
 
   // TITLE: Element getter
 
+  /**
+   * Returns the current targets held by this instance.
+   *
+   * @returns {ConstructorElValues[]} - The instance's targets element.
+   */
+  get elements() {
+    return [...this.#el];
+  }
+
   /**
    * Iterates over all elements, executing the provided callback on each.
    * @param {(element: TinyHtmlAny, index: number, items: TinyHtmlAny[]) => void} callback - Function invoked for each element.
    * @returns {this} The current instance for chaining.
    */
   forEach(callback) {
-    const elems = this.getAll().map((el, index) => this.extract(index));
+    const elems = this.elements.map((el, index) => this.extract(index));
     for (const index in elems) callback(elems[index], Number(index), elems);
     return this;
   }
@@ -907,6 +916,7 @@ class TinyHtml {
   }
 
   /**
+   * @deprecated Use the getter {@link elements} instead.
    * Returns the current targets held by this instance.
    *
    * @returns {ConstructorElValues[]} - The instance's targets element.
@@ -6508,6 +6518,291 @@ class TinyHtml {
     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
@@ -6533,8 +6828,8 @@ 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|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) {
@@ -6542,25 +6837,20 @@ class TinyHtml {
 
     // Multiple attributes at once
     if (typeof name === 'object' && name !== null) {
-      Object.entries(name).forEach(([attr, val]) => {
-        if (val !== null && typeof val !== 'string')
-          throw new TypeError(`The value for "${attr}" must be a string or null.`);
+      Object.entries(name).forEach(([attr, val]) =>
         elems.forEach((elem) => {
           if (val === null) elem.removeAttribute(TinyHtml.getAttrName(attr));
-          else elem.setAttribute(TinyHtml.getAttrName(attr), val);
-        });
-      });
+          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);
+      else elem.setAttribute(TinyHtml.getAttrName(name), String(value));
     });
 
     return el;
@@ -6568,8 +6858,8 @@ class TinyHtml {
 
   /**
    * Set one or multiple attributes on an element.
-   * @param {string|Record<string, string|null>} name - Attribute name or an object of attributes.
-   * @param {string|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) {
@@ -6746,7 +7036,7 @@ class TinyHtml {
   static prop(el, name) {
     if (typeof name !== 'string')
       throw new TypeError('Invalid arguments passed to prop(). Expected string for "name".');
-    const elem = TinyHtml._preElem(el, 'attr');
+    const elem = TinyHtml._preElem(el, 'prop');
     // @ts-ignore
     return elem[name];
   }
@@ -6761,6 +7051,34 @@ class TinyHtml {
     return TinyHtml.prop(this, name);
   }
 
+  /**
+   * Set a property on elements.
+   * @template {TinyElement|TinyElement[]} T
+   * @param {T} el - Target element(s).
+   * @param {string} name - Property name.
+   * @param {any} value - Value to set.
+   * @returns {T}
+   */
+  static setProp(el, name, value) {
+    if (typeof name !== 'string' || name.trim() === '')
+      throw new Error('Property name must be a non-empty string.');
+    TinyHtml._preElems(el, 'setProp').forEach((elem) => {
+      // @ts-ignore
+      elem[name] = value;
+    });
+    return el;
+  }
+
+  /**
+   * Set a property on this element.
+   * @param {string} name - Property name.
+   * @param {any} value - Value to set.
+   * @returns {this} The same element.
+   */
+  setProp(name, value) {
+    return TinyHtml.setProp(this, name, value);
+  }
+
   /////////////////////////////////////////////////////
 
   // TITLE: Remove Element