jj 2.7.2 → 2.9.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
@@ -318,6 +319,39 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * @throws {TypeError} If `ref` is not a Node.
      */
     constructor(ref: T);
+    /**
+     * Gets the parent node wrapped in the most specific JJ wrapper available.
+     *
+     * @remarks
+     * Returns `null` when this node is detached and therefore has no parent.
+     *
+     * @example
+     * ```ts
+     * const text = JJT.fromStr('hello')
+     * JJHE.create('div').addChild(text)
+     * const parent = text.parent // JJHE
+     * ```
+     *
+     * @returns The wrapped parent node, or `null` if this node has no parent.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode | Node.parentNode}
+     */
+    get parent(): Wrapped | null;
+    /**
+     * Gets the child nodes wrapped in the most specific JJ wrappers available.
+     *
+     * @remarks
+     * Returns an empty array when this node has no children.
+     *
+     * @example
+     * ```ts
+     * const el = JJHE.create('div').addChild('hello', JJHE.create('span'))
+     * const children = el.children // [JJT, JJHE]
+     * ```
+     *
+     * @returns The wrapped child nodes.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes | Node.childNodes}
+     */
+    get children(): Wrapped[];
     /**
      * Clones the Node.
      *
@@ -326,6 +360,23 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/cloneNode | Node.cloneNode}
      */
     clone(deep?: boolean): Wrapped;
+    /**
+     * Removes this node from its parent.
+     *
+     * @remarks
+     * If the node has no parent, this method does nothing.
+     *
+     * @example
+     * ```ts
+     * const el = JJHE.create('div')
+     * doc.body.addChild(el)
+     * el.rm()
+     * ```
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild | Node.removeChild}
+     */
+    rm(): this;
     /**
      * Creates a Text node from a string and appends it to this Node.
      *
@@ -342,7 +393,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 +709,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 +763,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 +1006,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 +1100,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 +1137,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 +1280,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 +1418,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 +1429,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 +1710,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
@@ -318,6 +319,39 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * @throws {TypeError} If `ref` is not a Node.
      */
     constructor(ref: T);
+    /**
+     * Gets the parent node wrapped in the most specific JJ wrapper available.
+     *
+     * @remarks
+     * Returns `null` when this node is detached and therefore has no parent.
+     *
+     * @example
+     * ```ts
+     * const text = JJT.fromStr('hello')
+     * JJHE.create('div').addChild(text)
+     * const parent = text.parent // JJHE
+     * ```
+     *
+     * @returns The wrapped parent node, or `null` if this node has no parent.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode | Node.parentNode}
+     */
+    get parent(): Wrapped | null;
+    /**
+     * Gets the child nodes wrapped in the most specific JJ wrappers available.
+     *
+     * @remarks
+     * Returns an empty array when this node has no children.
+     *
+     * @example
+     * ```ts
+     * const el = JJHE.create('div').addChild('hello', JJHE.create('span'))
+     * const children = el.children // [JJT, JJHE]
+     * ```
+     *
+     * @returns The wrapped child nodes.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes | Node.childNodes}
+     */
+    get children(): Wrapped[];
     /**
      * Clones the Node.
      *
@@ -326,6 +360,23 @@ declare class JJN<T extends Node = Node> extends JJET<T> {
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/cloneNode | Node.cloneNode}
      */
     clone(deep?: boolean): Wrapped;
+    /**
+     * Removes this node from its parent.
+     *
+     * @remarks
+     * If the node has no parent, this method does nothing.
+     *
+     * @example
+     * ```ts
+     * const el = JJHE.create('div')
+     * doc.body.addChild(el)
+     * el.rm()
+     * ```
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild | Node.removeChild}
+     */
+    rm(): this;
     /**
      * Creates a Text node from a string and appends it to this Node.
      *
@@ -342,7 +393,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 +709,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 +763,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 +1006,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 +1100,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 +1137,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 +1280,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 +1418,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 +1429,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 +1710,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.
@@ -405,6 +414,44 @@
       }
       super(ref);
     }
+    /**
+     * Gets the parent node wrapped in the most specific JJ wrapper available.
+     *
+     * @remarks
+     * Returns `null` when this node is detached and therefore has no parent.
+     *
+     * @example
+     * ```ts
+     * const text = JJT.fromStr('hello')
+     * JJHE.create('div').addChild(text)
+     * const parent = text.parent // JJHE
+     * ```
+     *
+     * @returns The wrapped parent node, or `null` if this node has no parent.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode | Node.parentNode}
+     */
+    get parent() {
+      const { parentNode } = this.ref;
+      return parentNode ? _JJN.wrap(parentNode) : null;
+    }
+    /**
+     * Gets the child nodes wrapped in the most specific JJ wrappers available.
+     *
+     * @remarks
+     * Returns an empty array when this node has no children.
+     *
+     * @example
+     * ```ts
+     * const el = JJHE.create('div').addChild('hello', JJHE.create('span'))
+     * const children = el.children // [JJT, JJHE]
+     * ```
+     *
+     * @returns The wrapped child nodes.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes | Node.childNodes}
+     */
+    get children() {
+      return _JJN.wrapAll(this.ref.childNodes);
+    }
     /**
      * Clones the Node.
      *
@@ -415,6 +462,29 @@
     clone(deep) {
       return _JJN.wrap(this.ref.cloneNode(deep));
     }
+    /**
+     * Removes this node from its parent.
+     *
+     * @remarks
+     * If the node has no parent, this method does nothing.
+     *
+     * @example
+     * ```ts
+     * const el = JJHE.create('div')
+     * doc.body.addChild(el)
+     * el.rm()
+     * ```
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild | Node.removeChild}
+     */
+    rm() {
+      const { parentNode } = this.ref;
+      if (parentNode) {
+        parentNode.removeChild(this.ref);
+      }
+      return this;
+    }
     /**
      * Creates a Text node from a string and appends it to this Node.
      *
@@ -431,9 +501,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 +568,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 +588,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 +644,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 +1406,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 +1478,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 +1491,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 +1655,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;
     }
     /**