jj 2.8.0 → 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

@@ -463,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.
    *
@@ -473,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.
    *