jj 2.7.2 → 2.9.0

package/SKILL.md

@@ -60,6 +60,8 @@ const nav = h(
 
 // Append to document body
 doc.body.ref.append(nav.ref)
+// Or using the wrapper API
+doc.body.addChild(nav.ref)
 ```
 
 For batch DOM operations, use `JJDF` (DocumentFragment) to avoid multiple reflows:
@@ -173,6 +175,20 @@ el.style('background-color', 'blue').style('padding', '10px')
 el.setAria('hidden', 'true').rmAria('label')
 ```
 
+Node traversal and detach helpers on `JJN`:
+
+```typescript
+const item = doc.find('#item', true)
+const parent = item.parent // wrapped parent or null
+const children = item.children // wrapped child nodes
+
+children.forEach((child) => {
+    console.log(child.ref)
+})
+
+item.rm() // detach from its current parent
+```
+
 ### 3. Type-Safe Element Creation
 
 JJ leverages TypeScript generics to ensure type safety and prevent LLM hallucinations:
@@ -614,8 +630,10 @@ Output: `doc/` folder with HTML documentation
 1. **Accessing the Native Node**: Always use `.ref` to access the underlying DOM node for operations not exposed by JJ
 2. **Event Listeners**: Use `.on()` and `.off()` for proper cleanup. Event handlers are automatically bound to the JJ\* instance, so `this` refers to the wrapper, not the DOM element. Use `function` instead of arrow functions (`=>`) for `.bind()` to work correctly. Use `this.ref` to access the native element.
 3. **Type Safety**: Use `JJHE.create()` for automatic type inference instead of generic parameters
-4. **Fragments**: Use JJDF for batch operations before appending
-5. **Error Messages**: Read them carefully—they suggest the correct approach
+4. **Tree Navigation**: Use `node.parent` and `node.children` to stay in JJ wrappers while traversing the DOM tree
+5. **Detaching Nodes**: Use `node.rm()` instead of reaching for native removal APIs unless you specifically need them
+6. **Fragments**: Use JJDF for batch operations before appending
+7. **Error Messages**: Read them carefully—they suggest the correct approach
 
 ## Anti-patterns to Avoid
 

package/lib/bundle.cjs

@@ -354,9 +354,9 @@ var JJN = class _JJN extends JJET {
    * 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);
   }
   /**
@@ -365,6 +365,7 @@ var JJN = class _JJN extends JJET {
    * @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
@@ -377,7 +378,15 @@ var JJN = class _JJN extends JJET {
    * @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.
@@ -454,6 +463,44 @@ var JJN = class _JJN extends JJET {
     }
     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.
    *
@@ -464,6 +511,29 @@ var JJN = class _JJN extends JJET {
   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.
    *
@@ -480,9 +550,9 @@ var JJN = class _JJN extends JJET {
    * @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;
   }
@@ -547,7 +617,7 @@ var JJNx = class extends JJN {
    * @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;
   }
@@ -567,7 +637,7 @@ var JJNx = class extends JJN {
    * @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;
   }
@@ -623,7 +693,7 @@ var JJNx = class extends JJN {
    * @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;
   }
@@ -1385,7 +1455,7 @@ var JJHE = class _JJHE extends JJEx {
    * @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;
   }
 };
@@ -1457,7 +1527,7 @@ var JJT = class _JJT extends JJN {
    * @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;
   }
   /**
@@ -1470,14 +1540,12 @@ var JJT = class _JJT extends JJN {
    * 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;
   }
   /**
@@ -1636,7 +1704,7 @@ var JJSE = class _JJSE extends JJEx {
    * @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;
   }
   /**