jj 2.6.0 → 2.8.0

package/lib/bundle.d.cts

@@ -217,7 +217,7 @@ declare class JJET<T extends EventTarget = EventTarget> {
      * @param args - Arguments to pass to the function.
      * @returns The return value of the function.
      */
-    run<R, Args extends any[]>(fn: (this: this, ...args: Args) => R, ...args: Args): R;
+    run<R, Args extends unknown[]>(fn: (this: this, ...args: Args) => R, ...args: Args): R;
 }
 
 /**
@@ -249,15 +249,16 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * This is useful for filtering the array that is passed to `append()`, `prepend()` or `setChildren()`
      *
      * @param x an unknown value
-     * @returns true if `x` is a string, Node (or its descendents), JJN (or its descendents)
+     * @returns true if `x` is a string, Node (or its descendent), JJN (or its descendent)
      */
-    static isWrapable(x: unknown): x is Wrappable;
+    static isWrappable(x: unknown): x is Wrappable;
     /**
      * Wraps a native DOM node or string into the most specific JJ wrapper available.
      *
      * @remarks
      * This function acts as a factory, inspecting the input type and returning the appropriate
      * subclass of `JJN` (e.g., `JJHE` for `HTMLElement`, `JJT` for `Text`).
+     * JJN.ts overrides this method to a richer version that handles all subclasses of JJN.
      *
      * @example
      * ```ts
@@ -342,7 +343,7 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createTextNode | document.createTextNode}
      */
-    addText(text?: string | null): this;
+    addText(...textArr: unknown[]): this;
 }
 
 declare abstract class JJNx<T extends Element | Document | DocumentFragment> extends JJN<T> {
@@ -658,8 +659,8 @@ declare class JJE<T extends Element = Element> extends JJNx<T> {
      * @throws {TypeError} If arguments are invalid types.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/setAttribute | Element.setAttribute}
      */
-    setAttr(name: string, value: any): this;
-    setAttr(obj: Record<string, any>): this;
+    setAttr(name: string, value: unknown): this;
+    setAttr(obj: Record<string, unknown>): this;
     /**
      * Removes one or more attributes from the Element.
      *
@@ -712,8 +713,8 @@ declare class JJE<T extends Element = Element> extends JJNx<T> {
      *
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes | ARIA Attributes}
      */
-    setAria(name: string, value: any): this;
-    setAria(obj: Record<string, any>): this;
+    setAria(name: string, value: unknown): this;
+    setAria(obj: Record<string, unknown>): this;
     /**
      * Removes one or more ARIA attributes from the Element.
      *
@@ -955,14 +956,14 @@ declare abstract class JJEx<T extends HTMLElement | SVGElement> extends JJE<T> {
      * ```ts
      * el.setData('myKey', 'myValue')  // Single
      * el.setData({ myKey: 'myValue', otherKey: 'otherValue' })  // Multiple
-     * el.setData('count', 42)  // Numbers are automatically converted
+     * el.setData('count', 42)  // Numbers are automatically converted to strings
      * ```
      *
      * @throws {TypeError} If arguments are invalid types.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset | HTMLElement.dataset}
      */
-    setData(name: string, value: any): this;
-    setData(obj: Record<string, any>): this;
+    setData(name: string, value?: string): this;
+    setData(obj: Record<string, string | undefined>): this;
     /**
      * Removes one or more data attributes from the HTMLElement.
      *
@@ -1049,7 +1050,7 @@ declare class JJHE<T extends HTMLElement = HTMLElement> extends JJEx<T> {
      * @throws {Error} If the HTMLElement does not have a value property.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/value | HTMLInputElement.value}
      */
-    setValue(value: any): this;
+    setValue(value: unknown): this;
     /**
      * Focuses the HTMLElement.
      *
@@ -1086,7 +1087,7 @@ declare class JJHE<T extends HTMLElement = HTMLElement> extends JJEx<T> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText | HTMLElement.innerText}
      */
-    setText(text?: any): this;
+    setText(text?: unknown): this;
 }
 
 /**
@@ -1229,7 +1230,7 @@ declare class JJSE<T extends SVGElement = SVGElement> extends JJEx<T> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
-    setText(text?: any): this;
+    setText(text?: unknown): this;
     /**
      * Sets the fill attribute.
      *
@@ -1367,7 +1368,7 @@ declare class JJT<T extends Text = Text> extends JJN<Text> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
-    setText(text?: any): this;
+    setText(text?: unknown): this;
     /**
      * Appends text to the existing content.
      *
@@ -1378,11 +1379,11 @@ declare class JJT<T extends Text = Text> extends JJN<Text> {
      * console.log(text.getText()) // 'hello world'
      * ```
      *
-     * @param text - The string to add to the existing contents. If null or undefined, nothing is added.
+     * @param textArr - The string to add to the existing contents. If null or undefined, nothing is added.
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
-    addText(text?: any): this;
+    addText(...textArr: unknown[]): this;
     /**
      * Clears the text content of the Text node.
      *
@@ -1659,7 +1660,7 @@ declare function fetchStyle(url: URL | string): Promise<CSSStyleSheet>;
  * @returns `true` if it tried to set the attribute; otherwise `false`.
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes | Responding to attribute changes}
  */
-declare function attr2prop(instance: HTMLElement, name: string, oldValue: any, newValue: any): boolean;
+declare function attr2prop(instance: HTMLElement, name: string, oldValue: unknown, newValue: unknown): boolean;
 /**
  * Registers the custom element with the browser and waits till it is defined.
  *

package/lib/bundle.d.ts

@@ -217,7 +217,7 @@ declare class JJET<T extends EventTarget = EventTarget> {
      * @param args - Arguments to pass to the function.
      * @returns The return value of the function.
      */
-    run<R, Args extends any[]>(fn: (this: this, ...args: Args) => R, ...args: Args): R;
+    run<R, Args extends unknown[]>(fn: (this: this, ...args: Args) => R, ...args: Args): R;
 }
 
 /**
@@ -249,15 +249,16 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * This is useful for filtering the array that is passed to `append()`, `prepend()` or `setChildren()`
      *
      * @param x an unknown value
-     * @returns true if `x` is a string, Node (or its descendents), JJN (or its descendents)
+     * @returns true if `x` is a string, Node (or its descendent), JJN (or its descendent)
      */
-    static isWrapable(x: unknown): x is Wrappable;
+    static isWrappable(x: unknown): x is Wrappable;
     /**
      * Wraps a native DOM node or string into the most specific JJ wrapper available.
      *
      * @remarks
      * This function acts as a factory, inspecting the input type and returning the appropriate
      * subclass of `JJN` (e.g., `JJHE` for `HTMLElement`, `JJT` for `Text`).
+     * JJN.ts overrides this method to a richer version that handles all subclasses of JJN.
      *
      * @example
      * ```ts
@@ -342,7 +343,7 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createTextNode | document.createTextNode}
      */
-    addText(text?: string | null): this;
+    addText(...textArr: unknown[]): this;
 }
 
 declare abstract class JJNx<T extends Element | Document | DocumentFragment> extends JJN<T> {
@@ -658,8 +659,8 @@ declare class JJE<T extends Element = Element> extends JJNx<T> {
      * @throws {TypeError} If arguments are invalid types.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/setAttribute | Element.setAttribute}
      */
-    setAttr(name: string, value: any): this;
-    setAttr(obj: Record<string, any>): this;
+    setAttr(name: string, value: unknown): this;
+    setAttr(obj: Record<string, unknown>): this;
     /**
      * Removes one or more attributes from the Element.
      *
@@ -712,8 +713,8 @@ declare class JJE<T extends Element = Element> extends JJNx<T> {
      *
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes | ARIA Attributes}
      */
-    setAria(name: string, value: any): this;
-    setAria(obj: Record<string, any>): this;
+    setAria(name: string, value: unknown): this;
+    setAria(obj: Record<string, unknown>): this;
     /**
      * Removes one or more ARIA attributes from the Element.
      *
@@ -955,14 +956,14 @@ declare abstract class JJEx<T extends HTMLElement | SVGElement> extends JJE<T> {
      * ```ts
      * el.setData('myKey', 'myValue')  // Single
      * el.setData({ myKey: 'myValue', otherKey: 'otherValue' })  // Multiple
-     * el.setData('count', 42)  // Numbers are automatically converted
+     * el.setData('count', 42)  // Numbers are automatically converted to strings
      * ```
      *
      * @throws {TypeError} If arguments are invalid types.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset | HTMLElement.dataset}
      */
-    setData(name: string, value: any): this;
-    setData(obj: Record<string, any>): this;
+    setData(name: string, value?: string): this;
+    setData(obj: Record<string, string | undefined>): this;
     /**
      * Removes one or more data attributes from the HTMLElement.
      *
@@ -1049,7 +1050,7 @@ declare class JJHE<T extends HTMLElement = HTMLElement> extends JJEx<T> {
      * @throws {Error} If the HTMLElement does not have a value property.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/value | HTMLInputElement.value}
      */
-    setValue(value: any): this;
+    setValue(value: unknown): this;
     /**
      * Focuses the HTMLElement.
      *
@@ -1086,7 +1087,7 @@ declare class JJHE<T extends HTMLElement = HTMLElement> extends JJEx<T> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText | HTMLElement.innerText}
      */
-    setText(text?: any): this;
+    setText(text?: unknown): this;
 }
 
 /**
@@ -1229,7 +1230,7 @@ declare class JJSE<T extends SVGElement = SVGElement> extends JJEx<T> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
-    setText(text?: any): this;
+    setText(text?: unknown): this;
     /**
      * Sets the fill attribute.
      *
@@ -1367,7 +1368,7 @@ declare class JJT<T extends Text = Text> extends JJN<Text> {
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
-    setText(text?: any): this;
+    setText(text?: unknown): this;
     /**
      * Appends text to the existing content.
      *
@@ -1378,11 +1379,11 @@ declare class JJT<T extends Text = Text> extends JJN<Text> {
      * console.log(text.getText()) // 'hello world'
      * ```
      *
-     * @param text - The string to add to the existing contents. If null or undefined, nothing is added.
+     * @param textArr - The string to add to the existing contents. If null or undefined, nothing is added.
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
-    addText(text?: any): this;
+    addText(...textArr: unknown[]): this;
     /**
      * Clears the text content of the Text node.
      *
@@ -1659,7 +1660,7 @@ declare function fetchStyle(url: URL | string): Promise<CSSStyleSheet>;
  * @returns `true` if it tried to set the attribute; otherwise `false`.
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes | Responding to attribute changes}
  */
-declare function attr2prop(instance: HTMLElement, name: string, oldValue: any, newValue: any): boolean;
+declare function attr2prop(instance: HTMLElement, name: string, oldValue: unknown, newValue: unknown): boolean;
 /**
  * Registers the custom element with the browser and waits till it is defined.
  *

package/lib/bundle.global.js

@@ -305,9 +305,9 @@
      * This is useful for filtering the array that is passed to `append()`, `prepend()` or `setChildren()`
      *
      * @param x an unknown value
-     * @returns true if `x` is a string, Node (or its descendents), JJN (or its descendents)
+     * @returns true if `x` is a string, Node (or its descendent), JJN (or its descendent)
      */
-    static isWrapable(x) {
+    static isWrappable(x) {
       return isStr(x) || isA(x, Node) || isA(x, _JJN);
     }
     /**
@@ -316,6 +316,7 @@
      * @remarks
      * This function acts as a factory, inspecting the input type and returning the appropriate
      * subclass of `JJN` (e.g., `JJHE` for `HTMLElement`, `JJT` for `Text`).
+     * JJN.ts overrides this method to a richer version that handles all subclasses of JJN.
      *
      * @example
      * ```ts
@@ -328,7 +329,15 @@
      * @throws {TypeError} If the input is not a Node, string, or JJ wrapper.
      */
     static wrap(raw) {
-      throw new ReferenceError(`The mixin is supposed to override this method.`);
+      if (isObj(raw)) {
+        if (isA(raw, _JJN)) {
+          return raw;
+        }
+        if (isA(raw, Node)) {
+          return new _JJN(raw);
+        }
+      }
+      throw typeErr("raw", "a Node", raw);
     }
     /**
      * Extracts the underlying native DOM node from a wrapper.
@@ -431,9 +440,9 @@
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createTextNode | document.createTextNode}
      */
-    addText(text) {
-      if (text) {
-        this.ref.appendChild(document.createTextNode(text));
+    addText(...textArr) {
+      if (textArr) {
+        this.ref.appendChild(document.createTextNode(textArr.join("")));
       }
       return this;
     }
@@ -498,7 +507,7 @@
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/append | Element.append}
      */
     addChild(...children) {
-      const nodes = JJN.unwrapAll(children.filter(JJN.isWrapable));
+      const nodes = JJN.unwrapAll(children.filter(JJN.isWrappable));
       this.ref.append(...nodes);
       return this;
     }
@@ -518,7 +527,7 @@
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/prepend | Element.prepend}
      */
     preChild(...children) {
-      const nodes = JJN.unwrapAll(children.filter(JJN.isWrapable));
+      const nodes = JJN.unwrapAll(children.filter(JJN.isWrappable));
       this.ref.prepend(...nodes);
       return this;
     }
@@ -574,7 +583,7 @@
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.replaceChildren}
      */
     setChildren(...children) {
-      const nodes = JJN.unwrapAll(children.filter(JJN.isWrapable));
+      const nodes = JJN.unwrapAll(children.filter(JJN.isWrappable));
       this.ref.replaceChildren(...nodes);
       return this;
     }
@@ -1336,7 +1345,7 @@
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText | HTMLElement.innerText}
      */
     setText(text) {
-      this.ref.innerText = text ?? "";
+      this.ref.innerText = text;
       return this;
     }
   };
@@ -1408,7 +1417,7 @@
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
     setText(text) {
-      this.ref.textContent = text ?? null;
+      this.ref.textContent = text;
       return this;
     }
     /**
@@ -1421,14 +1430,12 @@
      * console.log(text.getText()) // 'hello world'
      * ```
      *
-     * @param text - The string to add to the existing contents. If null or undefined, nothing is added.
+     * @param textArr - The string to add to the existing contents. If null or undefined, nothing is added.
      * @returns This instance for chaining.
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
-    addText(text) {
-      if (text != null) {
-        this.ref.textContent += text;
-      }
+    addText(...textArr) {
+      this.setText(this.getText() + textArr.join(""));
       return this;
     }
     /**
@@ -1587,7 +1594,7 @@
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
      */
     setText(text) {
-      this.ref.textContent = text ?? "";
+      this.ref.textContent = text;
       return this;
     }
     /**