jj 2.4.0 → 2.5.0

package/lib/bundle.js

@@ -97,12 +97,6 @@ function nextAnimationFrame() {
 function sleep(ms = 0) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function on(target, eventName, handler) {
-  target.addEventListener(eventName, handler);
-}
-function off(target, eventName, handler) {
-  target.removeEventListener(eventName, handler);
-}
 async function cssToStyle(css) {
   const sheet = new CSSStyleSheet();
   return await sheet.replace(css);
@@ -132,8 +126,101 @@ function keb2cam(str) {
   return str.replace(/^-+|-+$/g, "").replace(/-+([a-z])/g, (g, c) => c.toUpperCase());
 }
 
+// src/JJET.ts
+var JJET = class _JJET {
+  static from(ref) {
+    return new _JJET(ref);
+  }
+  #ref;
+  /**
+   * Creates a JJET instance.
+   *
+   * @param ref - The EventTarget to wrap.
+   * @throws {TypeError} If `ref` is not an EventTarget.
+   */
+  constructor(ref) {
+    if (!isA(ref, EventTarget)) {
+      throw new TypeError(`JJET expects an EventTarget instance. Got ${ref} (${typeof ref}). `);
+    }
+    this.#ref = ref;
+  }
+  /**
+   * Gets the underlying DOM object.
+   */
+  get ref() {
+    return this.#ref;
+  }
+  /**
+   * Adds an event listener.
+   *
+   *  * @example
+   * ```ts
+   * JJET.from(window).on('resize', () => console.log('resized'))
+   * ```
+   * @param eventName - The name of the event.
+   * @param handler - The event handler.
+   * @param options - Optional event listener options.
+   * @returns This instance for chaining.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener | EventTarget.addEventListener}
+   */
+  on(eventName, handler, options) {
+    this.ref.addEventListener(eventName, handler, options);
+    return this;
+  }
+  /**
+   * Removes an event listener.
+   *
+   *  * @example
+   * ```ts
+   * JJET.from(window).off('resize', previouslyAttachedHandler)
+   * ```
+   * @param eventName - The name of the event.
+   * @param handler - The event handler.
+   * @param options - Optional event listener options or boolean.
+   * @returns This instance for chaining.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener | EventTarget.removeEventListener}
+   */
+  off(eventName, handler, options) {
+    this.ref.removeEventListener(eventName, handler, options);
+    return this;
+  }
+  /**
+   * Dispatches an Event at the specified EventTarget.
+   *
+   * @param event - The Event object to dispatch.
+   * @returns This instance for chaining.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent | EventTarget.dispatchEvent}
+   */
+  trigger(event) {
+    this.ref.dispatchEvent(event);
+    return this;
+  }
+  /**
+   * Runs a function in the context of this JJET instance.
+   *
+   * @example
+   * ```ts
+   * node.run(function() {
+   *   console.log(this.ref)
+   * })
+   * ```
+   * @remarks
+   * If you want to access the current JJ* instance using `this` keyword, you SHOULD use a `function` not an arrow function.
+   * If the function throws, `run()` doesn't swallow the exception.
+   * So if you're expecting an error, make sure to wrap it in a `try..catch` block and handle the exception.
+   * If the function returns a promise, you can `await` on the response.
+   *
+   * @param fn - The function to run. `this` inside the function will refer to this JJET instance.
+   * @param args - Arguments to pass to the function.
+   * @returns The return value of the function.
+   */
+  run(fn, ...args) {
+    return fn.call(this, ...args);
+  }
+};
+
 // src/JJN.ts
-var JJN = class _JJN {
+var JJN = class _JJN extends JJET {
   /**
    * Creates a JJN instance from a Node reference.
    *
@@ -201,7 +288,7 @@ var JJN = class _JJN {
       return document.createTextNode(obj);
     }
     if (!isObj(obj)) {
-      throw new TypeError(`Expected an object. Got ${obj} (${typeof obj})`);
+      throw new TypeError(`JJN.unwrap() expects a string, DOM Node, or JJ wrapper. Got ${obj} (${typeof obj}). `);
     }
     if (isA(obj, Node)) {
       return obj;
@@ -209,7 +296,9 @@ var JJN = class _JJN {
     if (isA(obj, _JJN)) {
       return obj.ref;
     }
-    throw new TypeError(`Could not unwrap ${obj} (${typeof obj})`);
+    throw new TypeError(
+      `Could not unwrap ${obj} (${typeof obj}). Expected a string, Node, or JJ wrapper. Make sure you're passing a valid DOM element or JJ wrapper.`
+    );
   }
   /**
    * Wraps an iterable object (e.g. an array of wrapped or DOM elements).
@@ -239,7 +328,6 @@ var JJN = class _JJN {
   static unwrapAll(iterable) {
     return Array.from(iterable, _JJN.unwrap);
   }
-  #ref;
   /**
    * Creates an instance of JJN.
    *
@@ -248,18 +336,14 @@ var JJN = class _JJN {
    */
   constructor(ref) {
     if (!isA(ref, Node)) {
-      throw new TypeError(`Expected a Node. Got ${ref} (${typeof ref})`);
+      throw new TypeError(
+        `JJN expects a Node instance. Got ${ref} (${typeof ref}). Use JJN.from(node) with a DOM Node, or check that you're passing a valid DOM element.`
+      );
     }
-    this.#ref = ref;
-  }
-  /**
-   * Gets the underlying DOM Node.
-   */
-  get ref() {
-    return this.#ref;
+    super(ref);
   }
   /**
-   * Clones the node.
+   * Clones the Node.
    *
    * @param deep - If true, clones the subtree.
    * @returns A new wrapped instance of the clone.
@@ -269,266 +353,197 @@ var JJN = class _JJN {
     return _JJN.wrap(this.ref.cloneNode(deep));
   }
   /**
-   * Appends children to this node.
+   * Creates a Text node from a string and appends it to this Node.
    *
    * @remarks
-   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
+   * This method is overridden in JJT to append to the existing text content instead.
    *
-   * @param children - The children to append (Nodes, strings, or Wrappers).
+   * @example
+   * ```ts
+   * el.addText('Hello ')
+   * el.addText('World')
+   * ```
+   *
+   * @param text - The text to add. If null or undefined, nothing is added.
    * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/append | Element.append}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild | Node.appendChild}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createTextNode | document.createTextNode}
    */
-  append(...children) {
-    const nodes = _JJN.unwrapAll(children.filter(_JJN.isWrapable));
-    const ref = this.ref;
-    for (const node of nodes) {
-      if (node) {
-        ref.appendChild(node);
-      }
+  addText(text) {
+    if (text) {
+      this.ref.appendChild(document.createTextNode(text));
     }
     return this;
   }
+};
+
+// src/JJNx.ts
+var JJNx = class extends JJN {
   /**
-   * Maps an array to children and appends them.
+   * Finds the first element matching a selector within this Element.
    *
    * @example
    * ```ts
-   * list.mapAppend(['a', 'b'], item => h('li', null, item))
+   * const span = el.query('span')  // Returns null if not found
+   * const span = el.query('span', true)  // Throws if not found
    * ```
    *
-   * @remarks
-   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
-   *
-   * @param array - The source array.
-   * @param mapFn - The mapping function returning a Wrappable.
-   * @returns This instance for chaining.
-   */
-  mapAppend(array, mapFn) {
-    return this.append(...array.map(mapFn));
-  }
-  /**
-   * Prepends children to this node.
-   *
-   * @remarks
-   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
-   *
-   * @param children - The children to prepend.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/prepend | Element.prepend}
+   * @param selector - The CSS selector.
+   * @param required - Whether to throw an error if not found. Defaults to false.
+   * @returns The wrapped element, or null if not found and required is false.
+   * @throws {TypeError} If selector is not a string or element not found and required is true.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector | Element.querySelector}
    */
-  prepend(...children) {
-    const nodes = _JJN.unwrapAll(children.filter(_JJN.isWrapable));
-    const ref = this.ref;
-    const first = ref.firstChild;
-    for (const node of nodes) {
-      if (node) {
-        ref.insertBefore(node, first);
-      }
+  query(selector, required = false) {
+    const queryResult = this.ref.querySelector(selector);
+    if (queryResult) {
+      return JJN.wrap(queryResult);
     }
-    return this;
+    if (required) {
+      throw new TypeError(
+        `Element with selector "${selector}" not found. Did you mean to call .query("${selector}", false) to return null instead? `
+      );
+    }
+    return null;
   }
   /**
-   * Maps an array to children and prepends them.
+   * Finds all elements matching a selector within this Element.
    *
    * @example
    * ```ts
-   * list.mapPrepend(['a', 'b'], item => JJHE.fromTag('li').setText(item))
+   * const items = el.queryAll('li')
    * ```
    *
-   * @remarks
-   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
-   *
-   * @param array - The source array.
-   * @param mapFn - The mapping function.
-   * @returns This instance for chaining.
+   * @param selector - The CSS selector.
+   * @returns An array of wrapped elements.
+   * @throws {TypeError} If selector is not a string.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelectorAll | Element.querySelectorAll}
    */
-  mapPrepend(array, mapFn) {
-    return this.prepend(...array.map(mapFn));
+  queryAll(selector) {
+    return JJN.wrapAll(this.ref.querySelectorAll(selector));
   }
   /**
-   * Replaces the existing children of this node with a specified new set of children.
+   * Appends children to this Element.
+   *
+   * @example
+   * ```ts
+   * el.append(h('span', null, 'hello'))
+   * ```
    *
    * @remarks
-   * If no children are specified, it essentially empties the node
    * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
    *
-   * @param children - The new children to set.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.replaceChildren}
-   */
-  setChildren(...children) {
-    return this.empty().append(...children.filter(_JJN.isWrapable));
-  }
-  /**
-   * Adds an event listener.
-   *
-   * @param eventName - The event name.
-   * @param handler - The event handler.
+   * @param children - The children to append.
    * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener | EventTarget.addEventListener}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/append | Element.append}
    */
-  on(eventName, handler) {
-    on(this.ref, eventName, handler);
+  append(...children) {
+    const nodes = JJN.unwrapAll(children.filter(JJN.isWrapable));
+    this.ref.append(...nodes);
     return this;
   }
   /**
-   * Removes an event listener.
+   * Prepends children to this Element.
    *
-   * @param eventName - The event name.
-   * @param handler - The event handler.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener | EventTarget.removeEventListener}
-   */
-  off(eventName, handler) {
-    off(this.ref, eventName, handler);
-    return this;
-  }
-  /**
-   * Removes this node from the DOM.
+   * @example
+   * ```ts
+   * el.prepend(h('span', null, 'first'))
+   * ```
    *
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild | Node.removeChild}
-   */
-  rm() {
-    this.ref.parentNode?.removeChild(this.ref);
-    return this;
-  }
-  /**
-   * Removes all children from this node.
+   * @remarks
+   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
    *
+   * @param children - The children to prepend.
    * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.replaceChildren}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/prepend | Element.prepend}
    */
-  empty() {
-    const element = this.ref;
-    while (element.firstChild) {
-      element.removeChild(element.firstChild);
-    }
+  prepend(...children) {
+    const nodes = JJN.unwrapAll(children.filter(JJN.isWrapable));
+    this.ref.prepend(...nodes);
     return this;
   }
   /**
-   * Runs a function in the context of this JJN instance.
+   * Maps an array to children and appends them.
    *
    * @example
    * ```ts
-   * div.run(function() {
-   *   this.addClass('active')
-   *   console.log(this.ref)
-   * })
+   * node.mapAppend(['a', 'b'], item => h('li', null, item))
    * ```
+   *
    * @remarks
-   * If you want to access the current JJ* instance using `this` keyword, you SHOULD use a `function` not an arrow function.
-   * If the function throws, `run()` doesn't swallow the exception.
-   * So if you're expecting an error, make sure to wrap it in a `try..catch` block and handle the exception.
-   * If the function returns a promise, you can `await` on the response.
+   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
    *
-   * @param fn - The function to run. `this` inside the function will refer to this JJN instance.
-   * @param args - Arguments to pass to the function.
-   * @returns The return value of the function.
+   * @param array - The source array.
+   * @param mapFn - The mapping function returning a Wrappable.
+   * @returns This instance for chaining.
    */
-  run(fn, ...args) {
-    return fn.call(this, ...args);
+  mapAppend(array, mapFn) {
+    return this.append(...array.map(mapFn));
   }
-};
-
-// src/JJT.ts
-var JJT = class _JJT extends JJN {
   /**
-   * Creates a JJT instance from a Text node.
+   * Maps an array to children and prepends them.
    *
    * @example
    * ```ts
-   * const textNode = document.createTextNode('foo')
-   * const jjText = JJT.from(textNode)
+   * node.mapPrepend(['a', 'b'], item => JJHE.fromTag('li').setText(item))
    * ```
    *
-   * @param text - The Text node.
-   * @returns A new JJT instance.
-   * @throws {TypeError} If `text` is not a Text node.
-   */
-  static from(text) {
-    if (!isA(text, Text)) {
-      throw new TypeError(`Expected a Text object. Got: ${text} (${typeof text})`);
-    }
-    return new _JJT(text);
-  }
-  /**
-   * Creates an instance of JJT.
-   *
-   * @example
-   * ```ts
-   * const text = new JJT('Hello World')
-   * ```
+   * @remarks
+   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
    *
-   * @param ref - The Text node or a string to create a Text node from.
-   * @throws {TypeError} If `ref` is not a Text node or string.
+   * @param array - The source array.
+   * @param mapFn - The mapping function.
+   * @returns This instance for chaining.
    */
-  constructor(ref) {
-    if (isStr(ref)) {
-      super(document.createTextNode(ref));
-    } else if (isA(ref, Text)) {
-      super(ref);
-    } else {
-      throw new TypeError(`Expected a Text. Got: ${ref} (${typeof ref})`);
-    }
+  mapPrepend(array, mapFn) {
+    return this.prepend(...array.map(mapFn));
   }
   /**
-   * Gets the text content.
+   * Replaces the existing children of an Element with a specified new set of children.
    *
-   * @returns The text content.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
-   */
-  getText() {
-    return this.ref.textContent ?? "";
-  }
-  /**
-   * Sets the text content.
+   * @remarks
+   * If no children are provided, it empties the Element.
+   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
    *
    * @example
    * ```ts
-   * text.setText('New content')
+   * el.setChildren(h('p', null, 'New Content'))
    * ```
-   *
-   * @param text - The text to set.
+   * @param children - The children to replace with.
    * @returns This instance for chaining.
-   * @throws {TypeError} If `text` is not a string.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.replaceChildren}
    */
-  setText(text) {
-    if (!isStr(text)) {
-      throw new TypeError(`Expected a string. Got: ${text} (${typeof text})`);
-    }
-    this.ref.textContent = text;
+  setChildren(...children) {
+    const nodes = JJN.unwrapAll(children.filter(JJN.isWrapable));
+    this.ref.replaceChildren(...nodes);
     return this;
   }
   /**
-   * Clears the text content.
-   *
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
-   */
-  empty() {
-    return this.setText("");
-  }
-  /**
-   * Sets the text content to multiple lines joined by newline.
+   * Removes all children from this Element.
    *
    * @example
    * ```ts
-   * text.addLines('Line 1', 'Line 2')
+   * el.empty()
    * ```
    *
-   * @param lines - The lines of text.
    * @returns This instance for chaining.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.setChildren}
    */
-  addLines(...lines) {
-    return this.setText(lines.join("\n"));
+  empty() {
+    this.setChildren();
+    return this;
   }
 };
 
+// src/internal.ts
+function errMsg(varName, expected, received) {
+  return `Expected '${varName}' to be ${expected}. Got ${received} (${typeof received})`;
+}
+function typeErr(varName, expected, received) {
+  return new TypeError(errMsg(varName, expected, received));
+}
+
 // src/JJDF.ts
-var JJDF = class _JJDF extends JJN {
+var JJDF = class _JJDF extends JJNx {
   /**
    * Creates a JJDF instance from a DocumentFragment reference.
    *
@@ -571,6 +586,34 @@ var JJDF = class _JJDF extends JJN {
     }
     super(ref);
   }
+  /**
+   * Finds an element by ID within this DocumentFragment.
+   *
+   * @example
+   * ```ts
+   * const el = frag.byId('header')  // Returns null if not found
+   * const el = frag.byId('header', true)  // Throws if not found
+   * ```
+   *
+   * @param id - The ID to search for.
+   * @param required - Whether to throw an error if not found. Defaults to false.
+   * @returns The wrapped element, or null if not found and required is false.
+   * @throws {TypeError} If id is not a string or element not found and required is true.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/getElementById | DocumentFragment.getElementById}
+   */
+  byId(id, required = false) {
+    if (!isStr(id)) {
+      throw typeErr("id", "a string", id);
+    }
+    const el = this.ref.getElementById(id);
+    if (el) {
+      return JJN.wrap(el);
+    }
+    if (required) {
+      throw new TypeError(`Element with id ${id} not found`);
+    }
+    return null;
+  }
 };
 
 // src/JJSR.ts
@@ -597,12 +640,14 @@ var JJSR = class _JJSR extends JJDF {
    */
   constructor(shadowRoot) {
     if (!isA(shadowRoot, ShadowRoot)) {
-      throw new TypeError(`Expected a ShadowRoot. Got ${shadowRoot} (${typeof shadowRoot})`);
+      throw new TypeError(
+        `JJSR expects a ShadowRoot instance. Got ${shadowRoot} (${typeof shadowRoot}). Access a shadow root using element.shadowRoot after calling element.attachShadow().`
+      );
     }
     super(shadowRoot);
   }
   /**
-   * Gets the inner HTML of the shadow root.
+   * Gets the inner HTML of the ShadowRoot.
    *
    * @returns The inner HTML string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML | Element.innerHTML}
@@ -611,7 +656,7 @@ var JJSR = class _JJSR extends JJDF {
     return this.ref.innerHTML;
   }
   /**
-   * Sets the inner HTML of the shadow root.
+   * Sets the inner HTML of the ShadowRoot.
    *
    * @example
    * ```ts
@@ -628,7 +673,7 @@ var JJSR = class _JJSR extends JJDF {
     return this;
   }
   /**
-   * Adds constructed stylesheets to the shadow root.
+   * Adds constructed stylesheets to the ShadowRoot.
    *
    * @example
    * ```ts
@@ -648,7 +693,7 @@ var JJSR = class _JJSR extends JJDF {
 };
 
 // src/JJE.ts
-var JJE = class _JJE extends JJN {
+var JJE = class _JJE extends JJNx {
   /**
    * Creates a JJE instance from an Element reference.
    *
@@ -671,35 +716,24 @@ var JJE = class _JJE extends JJN {
    */
   constructor(ref) {
     if (!isA(ref, Element)) {
-      throw new TypeError(`Expected an Element. Got: ${ref} (${typeof ref})`);
+      throw new TypeError(
+        `JJE expects an Element instance. Got ${ref} (${typeof ref}). Use JJE.from(element) with a DOM Element, or use the specific wrapper (JJHE for HTMLElement, JJSE for SVGElement).`
+      );
     }
     super(ref);
   }
-  /**
-   * Finds an element by ID within this element's context
-   *
-   * @remarks
-   * This method uses `Element.querySelector()` under the hood.
-   *
-   * @param id - The ID to search for.
-   * @param throwIfNotFound - Whether to throw an error if not found. Defaults to true.
-   * @returns The wrapped element, or null if not found and throwIfNotFound is false.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector | Element.querySelector}
-   */
-  byId(id, throwIfNotFound = true) {
-    if (!isStr(id)) {
-      throw new TypeError(`Expected a string id. Got ${id} (${typeof id})`);
-    }
-    return this.query(`#${id}`, throwIfNotFound);
-  }
   /**
    * Gets the value of an attribute.
    *
    * @param name - The name of the attribute.
    * @returns The attribute value, or null if not present.
+   * @throws {TypeError} If `name` is not a string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/getAttribute | Element.getAttribute}
    */
   getAttr(name) {
+    if (!isStr(name)) {
+      throw typeErr("name", "a string", name);
+    }
     return this.ref.getAttribute(name);
   }
   /**
@@ -707,62 +741,46 @@ var JJE = class _JJE extends JJN {
    *
    * @param name - The name of the attribute.
    * @returns `true` if the attribute exists, otherwise `false`.
+   * @throws {TypeError} If `name` is not a string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/hasAttribute | Element.hasAttribute}
    */
   hasAttr(name) {
-    return this.ref.hasAttribute(name);
-  }
-  /**
-   * Sets the value of an attribute.
-   *
-   * @param name - The name of the attribute.
-   * @param value - The value to set.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/setAttribute | Element.setAttribute}
-   */
-  setAttr(name, value) {
-    this.ref.setAttribute(name, value);
-    return this;
-  }
-  /**
-   * Sets multiple attributes at once.
-   *
-   * @example
-   * ```ts
-   * el.setAttrs({ id: 'my-id', class: 'my-class' })
-   * ```
-   *
-   * @param obj - An object where keys are attribute names and values are attribute values.
-   * @returns This instance for chaining.
-   * @throws {TypeError} If `obj` is not an object.
-   */
-  setAttrs(obj) {
-    if (!isObj(obj)) {
-      throw new TypeError(`Expected an object. Got: ${obj} (${typeof obj})`);
+    if (!isStr(name)) {
+      throw typeErr("name", "a string", name);
     }
-    for (const [name, value] of Object.entries(obj)) {
-      this.setAttr(name, value);
+    return this.ref.hasAttribute(name);
+  }
+  setAttr(nameOrObj, value) {
+    if (typeof nameOrObj === "string") {
+      this.ref.setAttribute(nameOrObj, value);
+    } else if (isObj(nameOrObj)) {
+      for (const [k, v] of Object.entries(nameOrObj)) {
+        this.ref.setAttribute(k, v);
+      }
+    } else {
+      throw typeErr("nameOrObj", "a string or object", nameOrObj);
     }
     return this;
   }
   /**
-   * Removes an attribute.
+   * Removes one or more attributes from the Element.
    *
-   * @param name - The name of the attribute to remove.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/removeAttribute | Element.removeAttribute}
-   */
-  rmAttr(name) {
-    return this.rmAttrs(name);
-  }
-  /**
-   * Removes multiple attributes.
+   * @example
+   * ```ts
+   * el.rmAttr('disabled')  // Remove single
+   * el.rmAttr('hidden', 'aria-hidden')  // Remove multiple
+   * ```
    *
-   * @param names - The names of the attributes to remove.
+   * @param names - The name(s) of the attribute(s) to remove.
    * @returns This instance for chaining.
+   * @throws {TypeError} If any name is not a string.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/removeAttribute | Element.removeAttribute}
    */
-  rmAttrs(...names) {
+  rmAttr(...names) {
     for (const name of names) {
+      if (!isStr(name)) {
+        throw typeErr("name", "a string", name);
+      }
       this.ref.removeAttribute(name);
     }
     return this;
@@ -780,9 +798,13 @@ var JJE = class _JJE extends JJN {
    *
    * @param name - The ARIA attribute suffix (e.g., 'label' for 'aria-label').
    * @returns The attribute value, or null if not present.
+   * @throws {TypeError} If `name` is not a string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes | ARIA Attributes}
    */
   getAria(name) {
+    if (!isStr(name)) {
+      throw typeErr("name", "a string", name);
+    }
     return this.ref.getAttribute(`aria-${name}`);
   }
   /**
@@ -790,34 +812,46 @@ var JJE = class _JJE extends JJN {
    *
    * @param name - The ARIA attribute suffix.
    * @returns `true` if the attribute exists.
+   * @throws {TypeError} If `name` is not a string.
    */
   hasAria(name) {
+    if (!isStr(name)) {
+      throw typeErr("name", "a string", name);
+    }
     return this.ref.hasAttribute(`aria-${name}`);
   }
+  setAria(nameOrObj, value) {
+    if (isStr(nameOrObj)) {
+      this.ref.setAttribute(`aria-${nameOrObj}`, value);
+    } else if (isObj(nameOrObj)) {
+      for (const [k, v] of Object.entries(nameOrObj)) {
+        this.ref.setAttribute(`aria-${k}`, v);
+      }
+    } else {
+      throw typeErr("nameOrObj", "a string or object", nameOrObj);
+    }
+    return this;
+  }
   /**
-   * Sets an ARIA attribute.
+   * Removes one or more ARIA attributes from the Element.
    *
    * @example
    * ```ts
-   * el.setAria('hidden', 'true') // sets aria-hidden="true"
+   * el.rmAria('hidden')  // Remove single
+   * el.rmAria('label', 'hidden')  // Remove multiple
    * ```
    *
-   * @param name - The ARIA attribute suffix.
-   * @param value - The value to set.
-   * @returns This instance for chaining.
-   */
-  setAria(name, value) {
-    this.ref.setAttribute(`aria-${name}`, value);
-    return this;
-  }
-  /**
-   * Removes an ARIA attribute.
-   *
-   * @param name - The ARIA attribute suffix.
+   * @param names - The ARIA attribute suffix(es) to remove.
    * @returns This instance for chaining.
+   * @throws {TypeError} If any name is not a string.
    */
-  rmAria(name) {
-    this.ref.removeAttribute(`aria-${name}`);
+  rmAria(...names) {
+    for (const name of names) {
+      if (!isStr(name)) {
+        throw typeErr("name", "a string", name);
+      }
+      this.ref.removeAttribute(`aria-${name}`);
+    }
     return this;
   }
   /**
@@ -829,71 +863,94 @@ var JJE = class _JJE extends JJN {
   getClass() {
     return this.getAttr("class");
   }
-  /**
-   * Sets the class attribute.
-   *
-   * @param className - The class string to set.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/className | Element.className}
-   */
-  setClass(className) {
-    return this.setAttr("class", className);
+  setClass(classNameOrMap) {
+    if (typeof classNameOrMap === "string") {
+      return this.setAttr("class", classNameOrMap);
+    }
+    for (const [className, condition] of Object.entries(classNameOrMap)) {
+      if (condition) {
+        this.ref.classList.add(className);
+      } else {
+        this.ref.classList.remove(className);
+      }
+    }
+    return this;
   }
   /**
-   * Removes the `class` attribute of the element.
-   *
-   * @remarks
-   * If you want to remove a few specific class instead of all, use `rmClasses`
+   * Adds one or more classes to the Element.
    *
-   * @returns This instance for chaining.
-   */
-  rmClass() {
-    return this.rmAttr("class");
-  }
-  /**
-   * Adds one or more classes to the element.
+   * @example
+   * ```ts
+   * el.addClass('btn', 'btn-primary')
+   * ```
    *
    * @param classNames - The classes to add.
    * @returns This instance for chaining.
+   * @throws {TypeError} If any class name is not a string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/classList | Element.classList}
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/add | DOMTokenList.add}
    */
   addClass(...classNames) {
+    for (const className of classNames) {
+      if (!isStr(className)) {
+        throw typeErr("className", "a string", className);
+      }
+    }
     this.ref.classList.add(...classNames);
     return this;
   }
   /**
-   * Removes one or more classes from the element.
+   * Removes one or more classes from the Element.
+   *
+   * @example
+   * ```ts
+   * el.rmClass('active')  // Remove single
+   * el.rmClass('btn', 'btn-primary')  // Remove multiple
+   * ```
    *
    * @param classNames - The classes to remove.
    * @returns This instance for chaining.
+   * @throws {TypeError} If any class name is not a string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/classList | Element.classList}
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/remove | DOMTokenList.remove}
    */
-  rmClasses(...classNames) {
+  rmClass(...classNames) {
+    for (const className of classNames) {
+      if (!isStr(className)) {
+        throw typeErr("className", "a string", className);
+      }
+    }
     this.ref.classList.remove(...classNames);
     return this;
   }
   /**
-   * Checks if the element has a specific class.
+   * Checks if the Element has a specific class.
    *
    * @param className - The class to check for.
    * @returns `true` if the element has the class.
+   * @throws {TypeError} If `className` is not a string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/classList | Element.classList}
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/contains | DOMTokenList.contains}
    */
   hasClass(className) {
+    if (!isStr(className)) {
+      throw typeErr("className", "a string", className);
+    }
     return this.ref.classList.contains(className);
   }
   /**
-   * Toggles a class on the element.
+   * Toggles a class on the Element.
    *
    * @param className - The class to toggle.
    * @returns This instance for chaining.
+   * @throws {TypeError} If `className` is not a string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/classList | Element.classList}
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle | DOMTokenList.toggle}
    */
   toggleClass(className) {
+    if (!isStr(className)) {
+      throw typeErr("className", "a string", className);
+    }
     this.ref.classList.toggle(className);
     return this;
   }
@@ -905,41 +962,39 @@ var JJE = class _JJE extends JJN {
    *
    * @param oldClassName - The class name to remove
    * @param newClassName - The class name to add
+   * @throws {TypeError} If either className is not a string.
    */
   replaceClass(oldClassName, newClassName) {
+    if (!isStr(oldClassName)) {
+      throw typeErr("oldClassName", "a string", oldClassName);
+    }
+    if (!isStr(newClassName)) {
+      throw typeErr("newClassName", "a string", newClassName);
+    }
     this.ref.classList.replace(oldClassName, newClassName);
     return this;
   }
   /**
-   * Adds a click event listener.
-   *
-   * @param handler - The event handler.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener | EventTarget.addEventListener}
-   */
-  onClick(handler) {
-    return this.on("click", handler);
-  }
-  /**
-   * Hides the element by setting the `hidden` attribute and `aria-hidden="true"`.
-   *
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden | hidden attribute}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden | aria-hidden}
-   */
+  
+       * Hides the Element by setting the `hidden` attribute and `aria-hidden="true"`.
+       *
+       * @returns This instance for chaining.
+       * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden | hidden attribute}
+       * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden | aria-hidden}
+       */
   hide() {
     return this.setAttr("hidden", "").setAttr("aria-hidden", "true");
   }
   /**
-   * Shows the element by removing the `hidden` and `aria-hidden` attributes.
+   * Shows the Element by removing the `hidden` and `aria-hidden` attributes.
    *
    * @returns This instance for chaining.
    */
   show() {
-    return this.rmAttrs("hidden", "aria-hidden");
+    return this.rmAttr("hidden", "aria-hidden");
   }
   /**
-   * Disables the element by setting the `disabled` attribute and `aria-disabled="true"`.
+   * Disables the Element by setting the `disabled` attribute and `aria-disabled="true"`.
    *
    * @returns This instance for chaining.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled | disabled attribute}
@@ -949,49 +1004,18 @@ var JJE = class _JJE extends JJN {
     return this.setAttr("disabled", "").setAttr("aria-disabled", "true");
   }
   /**
-   * Enables the element by removing the `disabled` and `aria-disabled` attributes.
+   * Enables the Element by removing the `disabled` and `aria-disabled` attributes.
    *
    * @returns This instance for chaining.
    */
   enable() {
-    return this.rmAttrs("disabled", "aria-disabled");
-  }
-  /**
-   * Gets the title attribute.
-   *
-   * @returns The title, or null if not set.
-   */
-  getTitle() {
-    return this.getAttr("title");
-  }
-  /**
-   * Sets the title attribute.
-   *
-   * @param title - The title to set.
-   * @returns This instance for chaining.
-   */
-  setTitle(title) {
-    return this.setAttr("title", title);
-  }
-  /**
-   * Sets the id attribute.
-   *
-   * @param id - The id to set.
-   * @returns This instance for chaining.
-   */
-  setId(id) {
-    return this.setAttr("id", id);
+    return this.rmAttr("disabled", "aria-disabled");
   }
   /**
-   * Gets the id attribute.
+   * Gets the inner HTML of the Element.
    *
-   * @returns The id, or null if not set.
-   */
-  getId() {
-    return this.getAttr("id");
-  }
-  /**
-   * Gets the inner HTML of the element.
+   * @remarks
+   * This method operates on `innerHTML`. The method name is kept short for convenience.
    *
    * @returns The inner HTML string.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML | Element.innerHTML}
@@ -1000,18 +1024,22 @@ var JJE = class _JJE extends JJN {
     return this.ref.innerHTML;
   }
   /**
-   * Sets the inner HTML of the element.
+   * Sets the inner HTML of the Element.
+   *
+   * @remarks
+   * This method operates on `innerHTML`. The method name is kept short for convenience.
+   * Pass an empty string, `null`, or `undefined` to clear the content.
    *
-   * @param html - The HTML string to set.
+   * @param html - The HTML string to set, or null/undefined to clear.
    * @returns This instance for chaining.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML | Element.innerHTML}
    */
   setHTML(html) {
-    this.ref.innerHTML = html;
+    this.ref.innerHTML = html ?? "";
     return this;
   }
   /**
-   * Attaches a Shadow DOM to the element and optionally sets its content and styles.
+   * Attaches a Shadow DOM to the Element and optionally sets its content and styles.
    *
    * @remarks
    * We prevent FOUC by assigning the template and CSS in one go.
@@ -1039,7 +1067,7 @@ var JJE = class _JJE extends JJN {
     return this;
   }
   /**
-   * Gets a wrapper around the element's Shadow Root, if it exists.
+   * Gets a wrapper around the Element's Shadow Root, if it exists.
    *
    * @returns A JJSR instance wrapping the shadow root, or null if no shadow root exists.
    */
@@ -1048,40 +1076,107 @@ var JJE = class _JJE extends JJN {
   }
 };
 
-// src/JJHE.ts
-var JJHE = class _JJHE extends JJE {
+// src/JJEx.ts
+var JJEx = class extends JJE {
   /**
-   * Creates a JJHE instance from an HTMLElement reference.
+   * Gets a data attribute from the HTMLElement.
    *
    * @example
    * ```ts
-   * const el = JJHE.from(document.getElementById('my-id'))
+   * const value = el.getData('my-key')
    * ```
    *
-   * @param ref - The HTMLElement.
-   * @returns A new JJHE instance.
+   * @param name - The data attribute name (in camelCase).
+   * @returns The value of the attribute, or undefined if not set.
+   * @throws {TypeError} If `name` is not a string.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset | HTMLElement.dataset}
    */
-  static from(ref) {
-    return new _JJHE(ref);
+  getData(name) {
+    if (!isStr(name)) {
+      throw typeErr("name", "a string", name);
+    }
+    return this.ref.dataset[name];
   }
   /**
-   * Creates a JJHE instance from a tag name.
+   * Checks if a data attribute exists on the HTMLElement.
    *
    * @example
    * ```ts
-   * const div = JJHE.fromTag('div')
-   * const input = JJHE.fromTag('input', { is: 'custom-input' })
+   * if (el.hasData('my-key')) {
+   *   // ...
+   * }
    * ```
    *
-   * @param tagName - The tag name.
-   * @param options - Element creation options.
+   * @param name - The data attribute name (in camelCase).
+   * @returns True if the attribute exists, false otherwise.
+   * @throws {TypeError} If `name` is not a string.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset | HTMLElement.dataset}
+   */
+  hasData(name) {
+    if (!isStr(name)) {
+      throw typeErr("name", "a string", name);
+    }
+    return hasProp(this.ref.dataset, name);
+  }
+  setData(nameOrObj, value) {
+    if (typeof nameOrObj === "string") {
+      this.ref.dataset[nameOrObj] = value;
+    } else if (isObj(nameOrObj)) {
+      for (const [k, v] of Object.entries(nameOrObj)) {
+        this.ref.dataset[k] = v;
+      }
+    } else {
+      throw typeErr("nameOrObj", "a string or object", nameOrObj);
+    }
+    return this;
+  }
+  /**
+   * Removes one or more data attributes from the HTMLElement.
+   *
+   * @example
+   * ```ts
+   * el.rmData('myKey')  // Remove single
+   * el.rmData('myKey', 'otherKey')  // Remove multiple
+   * ```
+   *
+   * @param names - The data attribute name(s) (in camelCase).
+   * @returns This instance for chaining.
+   * @throws {TypeError} If any name is not a string.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset | HTMLElement.dataset}
+   */
+  rmData(...names) {
+    for (const name of names) {
+      if (!isStr(name)) {
+        throw typeErr("name", "a string", name);
+      }
+      delete this.ref.dataset[name];
+    }
+    return this;
+  }
+};
+
+// src/JJHE.ts
+var JJHE = class _JJHE extends JJEx {
+  /**
+   * Creates a JJHE instance from an HTMLElement reference.
+   *
+   * @example
+   * ```ts
+   * const el = JJHE.from(document.getElementById('my-id'))  // from an existing HTMLElement
+   * const el = JJHE.from(new document.createElement('div')) // from a new HTMLElement
+   * ```
+   *
+   * @param ref - The HTMLElement.
    * @returns A new JJHE instance.
-   * @throws {TypeError} If `tagName` is not a string.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement | document.createElement}
    */
+  static from(ref) {
+    return new _JJHE(ref);
+  }
   static fromTag(tagName, options) {
     if (!isStr(tagName)) {
-      throw new TypeError(`Expected a string for tagName. Got: ${tagName} (${typeof tagName})`);
+      throw new TypeError(
+        `JJHE.fromTag() expects tagName to be a string (e.g., 'div', 'button'). Got ${tagName} (${typeof tagName}). Did you mean to use a string literal like 'div'?`
+      );
     }
     return new _JJHE(document.createElement(tagName, options));
   }
@@ -1093,45 +1188,52 @@ var JJHE = class _JJHE extends JJE {
    */
   constructor(ref) {
     if (!isA(ref, HTMLElement)) {
-      throw new TypeError(`Expected an HTMLElement. Got ${ref} (${typeof ref})`);
+      throw new TypeError(
+        `JJHE expects an HTMLElement. Got ${ref} (${typeof ref}). If you have a DOM node, use JJHE.from(element). If creating a new element, use JJHE.fromTag('div').`
+      );
     }
     super(ref);
   }
   /**
-   * Gets the value property of the element (e.g. for inputs).
+   * Gets the value property of the HTMLElement (e.g. for inputs).
    *
    * @returns The value.
-   * @throws {Error} If the element does not have a value property.
+   * @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}
    */
   getValue() {
     if (!hasProp(this.ref, "value")) {
-      throw new Error("Element does not have a value property");
+      throw new Error(
+        `Cannot get value from <${this.ref.tagName.toLowerCase()}>. The value property only exists on form elements (input, textarea, select). If you need text content, try .getText() instead.`
+      );
     }
     return this.ref.value;
   }
   /**
-   * Sets the value property of the element.
+   * Sets the value property of the HTMLElement.
    *
    * @example
    * ```ts
    * input.setValue('new value')
+   * input.setValue(42)  // Numbers are automatically converted
    * ```
    *
    * @param value - The value to set.
    * @returns This instance for chaining.
-   * @throws {Error} If the element does not have a value property.
+   * @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) {
     if (!hasProp(this.ref, "value")) {
-      throw new Error("Element does not have a value property");
+      throw new Error(
+        `Cannot set value on <${this.ref.tagName.toLowerCase()}>. The value property only exists on form elements (input, textarea, select). If you need to set text content, try .setText() instead.`
+      );
     }
     this.ref.value = value;
     return this;
   }
   /**
-   * Focuses the element.
+   * Focuses the HTMLElement.
    *
    * @returns This instance for chaining.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus | HTMLElement.focus}
@@ -1141,7 +1243,7 @@ var JJHE = class _JJHE extends JJE {
     return this;
   }
   /**
-   * Clicks the element.
+   * Clicks the HTMLElement.
    *
    * @returns This instance for chaining.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click | HTMLElement.click}
@@ -1151,7 +1253,10 @@ var JJHE = class _JJHE extends JJE {
     return this;
   }
   /**
-   * Gets the inner text of the element.
+   * Gets the inner text of the HTMLElement.
+   *
+   * @remarks
+   * This method operates on `innerText`. The method name is kept short for convenience.
    *
    * @returns The inner text.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText | HTMLElement.innerText}
@@ -1160,50 +1265,230 @@ var JJHE = class _JJHE extends JJE {
     return this.ref.innerText;
   }
   /**
-   * Sets the inner text of the element.
+   * Sets the inner text of the HTMLElement.
+   *
+   * @remarks
+   * This method operates on `innerText`. The method name is kept short for convenience.
+   * Pass an empty string, `null`, or `undefined` to clear the content.
+   * Numbers and booleans are automatically converted to strings.
+   *
+   * @param text - The text to set, or null/undefined to clear.
+   * @returns This instance for chaining.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText | HTMLElement.innerText}
+   */
+  setText(text) {
+    this.ref.innerText = text ?? "";
+    return this;
+  }
+};
+
+// src/JJT.ts
+var JJT = class _JJT extends JJN {
+  /**
+   * Creates a JJT instance from a Text node.
+   *
+   * @example
+   * ```ts
+   * const textNode = document.createTextNode('foo')
+   * const text = JJT.from(textNode)
+   * ```
+   *
+   * @param text - The Text node.
+   * @returns A new JJT instance.
+   * @throws {TypeError} If `text` is not a Text node.
+   */
+  static from(text) {
+    return new _JJT(text);
+  }
+  static fromStr(text) {
+    return new _JJT(document.createTextNode(text));
+  }
+  /**
+   * Creates an instance of JJT.
+   *
+   * @example
+   * ```ts
+   * const text = new JJT('Hello World')
+   * ```
+   *
+   * @param ref - The Text node or a string to create a Text node from.
+   * @throws {TypeError} If `ref` is not a Text node or string.
+   */
+  constructor(ref) {
+    if (!isA(ref, Text)) {
+      throw new TypeError(
+        `JJT expects a Text node. Got ${ref} (${typeof ref}). Create a Text node with JJT.fromStr() or document.createTextNode('text').`
+      );
+    }
+    super(ref);
+  }
+  /**
+   * Gets the text content of the Text node.
+   *
+   * @example
+   * ```ts
+   * const content = text.getText()
+   * ```
+   *
+   * @returns The text content.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
+   */
+  getText() {
+    return this.ref.textContent;
+  }
+  /**
+   * Sets the text content of the Text node.
+   *
+   * @example
+   * ```ts
+   * text.setText('New content')
+   * ```
+   *
+   * @param text - The text to set. Set it to null or undefined to remove all text
+   * @returns This instance for chaining.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
+   */
+  setText(text) {
+    this.ref.textContent = text ?? null;
+    return this;
+  }
+  /**
+   * Appends text to the existing content.
+   *
+   * @example
+   * ```ts
+   * text.setText('hello')
+   * text.addText(' world')
+   * console.log(text.getText()) // 'hello world'
+   * ```
+   *
+   * @param text - 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;
+    }
+    return this;
+  }
+  /**
+   * Clears the text content of the Text node.
+   *
+   * @example
+   * ```ts
+   * text.empty()
+   * ```
+   *
+   * @returns This instance for chaining.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
+   */
+  empty() {
+    return this.setText("");
+  }
+};
+
+// src/JJD.ts
+var JJD = class _JJD extends JJNx {
+  /**
+   * Creates a JJD instance from a Document reference.
+   *
+   * @example
+   * ```ts
+   * const doc = JJD.from(document)
+   * ```
+   *
+   * @param ref - The Document instance.
+   * @returns A new JJD instance.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document | Document}
+   */
+  static from(ref) {
+    return new _JJD(ref);
+  }
+  /**
+   * Creates an instance of JJD.
    *
-   * @param text - The text to set.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText | HTMLElement.innerText}
+   * @param ref - The Document instance to wrap.
+   * @throws {TypeError} If `ref` is not a Document.
    */
-  setText(text) {
-    this.ref.innerText = text;
-    return this;
+  constructor(ref) {
+    if (!isA(ref, Document)) {
+      throw new TypeError(`JJD expects a Document instance. Got ${ref} (${typeof ref}). `);
+    }
+    super(ref);
   }
   /**
-   * Finds the first element matching a selector within this element's context.
+   * Finds an element by ID within this Document.
    *
-   * @param selector - The CSS selector.
-   * @param throwIfNotFound - Whether to throw an error if not found. Defaults to true.
-   * @returns The wrapped element, or null.
-   * @throws {TypeError} If the element is not found and `throwIfNotFound` is true.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector | Element.querySelector}
+   * @example
+   * ```ts
+   * const el = doc.byId('my-id')  // Returns null if not found
+   * const el = doc.byId('my-id', true)  // Throws if not found
+   * ```
+   *
+   * @param id - The ID to search for.
+   * @param required - Whether to throw an error if not found. Defaults to false.
+   * @returns The wrapped element, or null if not found and required is false.
+   * @throws {TypeError} If id is not a string or element not found and required is true.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | Document.getElementById}
    */
-  query(selector, throwIfNotFound = true) {
-    const el = this.ref.querySelector(selector);
+  byId(id, required = false) {
+    if (!isStr(id)) {
+      throw typeErr("id", "a string", id);
+    }
+    const el = this.ref.getElementById(id);
     if (el) {
       return JJN.wrap(el);
     }
-    if (throwIfNotFound) {
-      throw new TypeError(`Element with selector ${selector} not found`);
+    if (required) {
+      throw new TypeError(
+        `Element with id "${id}" not found in the document. Did you mean to call .byId("${id}", false) to return null instead? `
+      );
     }
     return null;
   }
   /**
-   * Finds all elements matching a selector within this element's context.
+   * Finds elements by class name in the Document.
    *
-   * @param selector - The CSS selector.
+   * @example
+   * ```ts
+   * const items = byClass('list-item')
+   * ```
+   *
+   * @param className - The class name to search for.
    * @returns An array of wrapped elements.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelectorAll | Element.querySelectorAll}
+   * @throws {TypeError} If className is not a string.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByClassName | Document.getElementsByClassName}
    */
-  queryAll(selector) {
-    return JJN.wrapAll(this.ref.querySelectorAll(selector));
+  byClass(className) {
+    if (!isStr(className)) {
+      throw typeErr("className", "a string", className);
+    }
+    return JJN.wrapAll(this.ref.getElementsByClassName(className));
+  }
+  /**
+   * Gets the `<head>` element of the document wrapped in a `JJHE` instance.
+   *
+   * @returns The wrapped head element.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/head | Document.head}
+   */
+  get head() {
+    return JJN.wrap(this.ref.head);
+  }
+  /**
+   * Gets the `<body>` element of the document wrapped in a `JJHE` instance.
+   *
+   * @returns The wrapped body element.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/body | Document.body}
+   */
+  get body() {
+    return JJN.wrap(this.ref.body);
   }
 };
 
 // src/JJSE.ts
 var SVG_NAMESPACE_URI = "http://www.w3.org/2000/svg";
-var JJSE = class _JJSE extends JJE {
+var JJSE = class _JJSE extends JJEx {
   /**
    * Creates a JJSE instance from an SVGElement reference.
    *
@@ -1238,7 +1523,9 @@ var JJSE = class _JJSE extends JJE {
    */
   static fromTag(tagName, options) {
     if (!isStr(tagName)) {
-      throw new TypeError(`Expected a string for tagName. Got: ${tagName} (${typeof tagName})`);
+      throw new TypeError(
+        `JJSE.fromTag() expects tagName to be a string (e.g., 'circle', 'path'). Got ${tagName} (${typeof tagName}). Did you mean to pass a string literal like 'circle'?`
+      );
     }
     const element = document.createElementNS(SVG_NAMESPACE_URI, tagName, options);
     return new _JJSE(element);
@@ -1251,12 +1538,22 @@ var JJSE = class _JJSE extends JJE {
    */
   constructor(ref) {
     if (!isA(ref, SVGElement)) {
-      throw new TypeError(`Expected an SVGElement. Got ${ref} (${typeof ref})`);
+      throw new TypeError(
+        `JJSE expects an SVGElement. Got ${ref} (${typeof ref}). Use JJSE.from(element) with an SVG element, or JJSE.fromTag('circle') to create one.`
+      );
     }
     super(ref);
   }
   /**
-   * Gets the text content of the element.
+   * Gets the text content of the SVGElement.
+   *
+   * @remarks
+   * This method operates on `textContent`. The method name is kept short for convenience.
+   *
+   * @example
+   * ```ts
+   * const text = svg.getText()
+   * ```
    *
    * @returns The text content.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
@@ -1265,18 +1562,35 @@ var JJSE = class _JJSE extends JJE {
     return this.ref.textContent ?? "";
   }
   /**
-   * Sets the text content of the element.
+   * Sets the text content of the SVGElement.
+   *
+   * @remarks
+   * This method operates on `textContent`. The method name is kept short for convenience.
+   * Pass an empty string, `null`, or `undefined` to clear the content.
+   * Numbers and booleans are automatically converted to strings.
    *
-   * @param text - The text to set.
+   * @example
+   * ```ts
+   * svg.setText('Hello SVG')
+   * svg.setText(null)  // Clear content
+   * svg.setText(42)  // Numbers are converted
+   * ```
+   *
+   * @param text - The text to set, or null/undefined to clear.
    * @returns This instance for chaining.
    * @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;
   }
   /**
-   * Clears the text content of the element.
+   * Clears the text content of the SVGElement.
+   *
+   * @example
+   * ```ts
+   * svg.empty()
+   * ```
    *
    * @returns This instance for chaining.
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent | Node.textContent}
@@ -1380,85 +1694,10 @@ var JJSE = class _JJSE extends JJE {
   }
 };
 
-// src/JJD.ts
-var JJD = class _JJD extends JJN {
-  /**
-   * Creates a JJD instance from a Document reference.
-   *
-   * @example
-   * ```ts
-   * const doc = JJD.from(document)
-   * ```
-   *
-   * @param ref - The Document instance.
-   * @returns A new JJD instance.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document | Document}
-   */
-  static from(ref) {
-    return new _JJD(ref);
-  }
-  /**
-   * Creates an instance of JJD.
-   *
-   * @param ref - The Document instance to wrap.
-   * @throws {TypeError} If `ref` is not a Document.
-   */
-  constructor(ref) {
-    if (!isA(ref, Document)) {
-      throw new TypeError(`Expected a Document. Got ${ref} (${typeof ref})`);
-    }
-    super(ref);
-  }
-  /**
-   * Gets the `<head>` element of the document wrapped in a `JJHE` instance.
-   *
-   * @returns The wrapped head element.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/head | Document.head}
-   */
-  get head() {
-    return JJN.wrap(this.ref.head);
-  }
-  /**
-   * Gets the `<body>` element of the document wrapped in a `JJHE` instance.
-   *
-   * @returns The wrapped body element.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/body | Document.body}
-   */
-  get body() {
-    return JJN.wrap(this.ref.body);
-  }
-  /**
-   * Sets the document title.
-   *
-   * @example
-   * ```ts
-   * JJD.from(document).setTitle('New Page Title')
-   * ```
-   *
-   * @param title - The new title string.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/title | Document.title}
-   */
-  setTitle(title) {
-    this.ref.title = title;
-    return this;
-  }
-  /**
-   * Gets the document title.
-   *
-   * @returns The current title of the document.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/title | Document.title}
-   */
-  getTitle() {
-    return this.ref.title;
-  }
-};
-
-// src/mixins.ts
-var { wrapAll, unwrap, unwrapAll, isWrapable } = JJN;
-function wrap(raw) {
+// src/JJN-wrap.ts
+JJN.wrap = function wrap(raw) {
   if (isStr(raw)) {
-    return JJT.from(document.createTextNode(raw));
+    return JJT.fromStr(raw);
   }
   if (!isObj(raw)) {
     throw new TypeError(`Expected an object to wrap. Got ${raw} (${typeof raw})`);
@@ -1491,233 +1730,13 @@ function wrap(raw) {
     return JJN.from(raw);
   }
   throw new TypeError(`Expected a Node to wrap. Got ${raw} (${typeof raw})`);
-}
-function byId(id, throwIfNotFound = true) {
-  const el = document.getElementById(id);
-  if (el) {
-    return wrap(el);
-  }
-  if (throwIfNotFound) {
-    throw new TypeError(`Found no element with id ${id} in the document.`);
-  }
-  return null;
-}
-function byClass(className) {
-  return wrapAll(document.getElementsByClassName(className));
-}
-function query(selector, throwIfNotFound = true) {
-  const queryResult = document.querySelector(selector);
-  if (queryResult) {
-    return wrap(queryResult);
-  }
-  if (throwIfNotFound) {
-    throw new TypeError(`Element with selector ${selector} not found`);
-  }
-  return null;
-}
-function queryAll(selector) {
-  return wrapAll(document.querySelectorAll(selector));
-}
-var DDF = {
-  /**
-   * Finds an element by ID within this Document or DocumentFragment.
-   *
-   * @example
-   * ```ts
-   * const el = doc.byId('header')
-   * ```
-   *
-   * @param this - The JJD or JJDF instance.
-   * @param id - The ID to search for.
-   * @param throwIfNotFound - Whether to throw an error if not found. Defaults to true.
-   * @returns The wrapped element, or null if not found and throwIfNotFound is false.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | Document.getElementById}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/getElementById | DocumentFragment.getElementById}
-   */
-  byId(id, throwIfNotFound = true) {
-    const el = this.ref.getElementById(id);
-    if (el) {
-      return wrap(el);
-    }
-    if (throwIfNotFound) {
-      throw new TypeError(`Element with id ${id} not found`);
-    }
-    return null;
-  }
-};
-var EDDF = {
-  /**
-   * Finds the first element matching a selector within this element's context.
-   *
-   * @example
-   * ```ts
-   * const span = div.query('span')
-   * ```
-   *
-   * @param this - The JJE, JJD or JJDF instance.
-   * @param selector - The CSS selector.
-   * @param throwIfNotFound - Whether to throw an error if not found. Defaults to true.
-   * @returns The wrapped element, or null.
-   * @throws {TypeError} If context is invalid or element not found (when requested).
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector | Element.querySelector}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector | Document.querySelector}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/querySelector | DocumentFragment.querySelector}
-   */
-  query(selector, throwIfNotFound = true) {
-    const queryResult = this.ref.querySelector(selector);
-    if (queryResult) {
-      return wrap(queryResult);
-    }
-    if (throwIfNotFound) {
-      throw new TypeError(`Element with selector ${selector} not found`);
-    }
-    return null;
-  },
-  /**
-   * Finds all elements matching a selector within this element's context.
-   *
-   * @example
-   * ```ts
-   * const items = list.queryAll('li')
-   * ```
-   *
-   * @param this - The JJE, JJD or JJDF instance.
-   * @param selector - The CSS selector.
-   * @returns An array of wrapped elements.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelectorAll | Element.querySelectorAll}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll | Document.querySelectorAll}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/querySelectorAll | DocumentFragment.querySelectorAll}
-   */
-  queryAll(selector) {
-    return wrapAll(this.ref.querySelectorAll(selector));
-  },
-  /**
-   * Appends children to this node using native append.
-   *
-   * @example
-   * ```ts
-   * myDiv.append(h('span', null, 'hello'))
-   * ```
-   *
-   * @remarks
-   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
-   *
-   * @param this - The JJE, JJD or JJDF instance.
-   * @param children - The children to append.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/append | Element.append}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/append | Document.append}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/append | DocumentFragment.append}
-   */
-  append(...children) {
-    const nodes = unwrapAll(children.filter(isWrapable));
-    this.ref.append(...nodes);
-    return this;
-  },
-  /**
-   * Prepends children to this node using native prepend.
-   *
-   * @example
-   * ```ts
-   * div.prepend(h('span', null, 'first'))
-   * ```
-   *
-   * @remarks
-   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
-   *
-   * @param this - The JJE, JJD or JJDF instance.
-   * @param children - The children to prepend.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/prepend | Element.prepend}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/prepend | Document.prepend}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/prepend | DocumentFragment.prepend}
-   */
-  prepend(...children) {
-    const nodes = unwrapAll(children.filter(isWrapable));
-    this.ref.prepend(...nodes);
-    return this;
-  },
-  /**
-   * Replaces the existing children of a node with a specified new set of children.
-   *
-   * @remarks
-   * If no children are provided, it empties the node.
-   *
-   * @example
-   * ```ts
-   * div.setChildren(h('p', null, 'New Content'))
-   * ```
-   *
-   * @remarks
-   * To make template codes easier, this function ignores any child that is not possible to `wrap()` (e.g. undefined, null, false).
-   *
-   * @param this - The JJE, JJD or JJDF instance.
-   * @param children - The children to replace with.
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.replaceChildren}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/replaceChildren | Document.replaceChildren}
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/replaceChildren | DocumentFragment.replaceChildren}
-   */
-  setChildren(...children) {
-    const nodes = unwrapAll(children.filter(isWrapable));
-    this.ref.replaceChildren(...nodes);
-    return this;
-  },
-  /**
-   * Removes all children from this node.
-   *
-   * @example
-   * ```ts
-   * div.empty()
-   * ```
-   *
-   * @returns This instance for chaining.
-   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.setChildren}
-   */
-  empty() {
-    this.setChildren();
-    return this;
-  }
 };
-var HESE = {
-  getData(name) {
-    return this.ref.dataset[name];
-  },
-  hasData(name) {
-    return hasProp(this.ref.dataset, name);
-  },
-  setData(name, value) {
-    this.ref.dataset[name] = value;
-    return this;
-  },
-  setDataObj(obj) {
-    for (const [name, value] of Object.entries(obj)) {
-      this.setData(name, value);
-    }
-    return this;
-  },
-  rmData(name) {
-    delete this.ref.dataset[name];
-    return this;
-  }
-};
-function assignPrototype(Class, ...mixins) {
-  for (const mixin of mixins) {
-    Object.assign(Class.prototype, mixin);
-  }
-}
-JJN.wrap = wrap;
-assignPrototype(JJE, EDDF);
-assignPrototype(JJD, DDF, EDDF);
-assignPrototype(JJDF, DDF, EDDF);
-assignPrototype(JJHE, HESE);
-assignPrototype(JJSE, HESE);
 
 // src/helpers.ts
 function h(tagName, attributes, ...children) {
   const ret = JJHE.fromTag(tagName).append(...children);
   if (attributes) {
-    ret.setAttrs(attributes);
+    ret.setAttr(attributes);
   }
   return ret;
 }
@@ -1737,28 +1756,28 @@ function linkAs(href) {
       throw new Error(`No 'as' attribute was specified and we failed to guess it from the URL: ${href}`);
   }
 }
-function createLinkPre(rel, href, as) {
+function createLinkPre(href, rel, as) {
   if (!isStr(href)) {
     if (!isA(href, URL)) {
-      throw new TypeError(`Expected a string or URL. Got ${href} (${typeof href})`);
+      throw typeErr("href", "a string or URL", href);
     }
     href = href.toString();
   }
   if (!["prefetch", "preload"].includes(rel)) {
-    throw new RangeError(`rel should be one of 'prefetch' or 'preload'. Got ${rel} (${typeof rel})`);
+    throw new RangeError(errMsg("rel", `'prefetch' or 'preload'`, rel));
   }
   if (!as) {
     as = linkAs(href);
     if (!as) {
-      throw new Error(`No 'as' attribute was specified and we failed to guess it from the URL: ${href}`);
+      throw new Error(`Could not guess 'as' attribute from URL: ${href}`);
     }
   }
   if (!["fetch", "style", "script"].includes(as)) {
-    throw new RangeError(`as should be one of 'fetch' or 'style'. Got ${as} (${typeof as})`);
+    throw new RangeError(errMsg("as", `'fetch', 'style', or 'script'`, as));
   }
-  return JJHE.fromTag("link").setAttrs({
-    rel,
+  return JJHE.fromTag("link").setAttr({
     href,
+    rel,
     as
   });
 }
@@ -1805,7 +1824,7 @@ async function templatePromise(templateConfig) {
   if (isA(templateConfig, HTMLElement)) {
     return templateConfig.outerHTML;
   }
-  throw new TypeError(`Expected a string, JJHE or HTMLElement. Got ${templateConfig} (${typeof templateConfig})`);
+  throw new TypeError(`Expected template to be a string, JJHE, or HTMLElement. Got ${typeof templateConfig}`);
 }
 async function stylePromise(styleConfig) {
   if (isFn(styleConfig)) {
@@ -1818,7 +1837,7 @@ async function stylePromise(styleConfig) {
   if (isStr(styleConfig)) {
     return await cssToStyle(styleConfig);
   }
-  throw new TypeError(`Expected a css string or CSSStyleSheet. Got ${styleConfig} (${typeof styleConfig})`);
+  throw new TypeError(`Expected style to be a CSS string or CSSStyleSheet. Got ${typeof styleConfig}`);
 }
 function stylePromises(styleConfigs) {
   if (!isArr(styleConfigs)) {
@@ -1912,20 +1931,25 @@ function attr2prop(instance, name, oldValue, newValue) {
 }
 async function registerComponent(name, constructor, options) {
   if (!isStr(name)) {
-    throw new TypeError(`Expected a string name. Got ${name} (${typeof name})`);
+    throw typeErr("name", "a string", name);
   }
   if (!isFn(constructor)) {
-    throw new TypeError(`Expected a constructor function. Got ${constructor} (${typeof constructor})`);
+    throw typeErr("constructor", "a function", constructor);
   }
   if (!customElements.get(name)) {
     customElements.define(name, constructor, options);
     await customElements.whenDefined(name);
   }
 }
+
+// src/index.ts
+var doc = JJD.from(document);
+var index_default = doc;
 export {
   JJD,
   JJDF,
   JJE,
+  JJET,
   JJHE,
   JJN,
   JJSE,
@@ -1934,30 +1958,20 @@ export {
   ShadowMaster,
   addLinkPre,
   attr2prop,
-  byClass,
-  byId,
   createLinkPre,
   cssToStyle,
+  index_default as default,
   fetchCss,
   fetchHtml,
   fetchStyle,
   fetchText,
   fileExt,
   h,
-  isWrapable,
   keb2cam,
   keb2pas,
   nextAnimationFrame,
-  off,
-  on,
   pas2keb,
-  query,
-  queryAll,
   registerComponent,
-  sleep,
-  unwrap,
-  unwrapAll,
-  wrap,
-  wrapAll
+  sleep
 };
 //# sourceMappingURL=bundle.js.map