jj 2.4.0 → 2.5.0

package/lib/JJE.d.ts

@@ -1,9 +1,6 @@
-import { JJN } from './JJN.js';
 import { JJSR } from './JJSR.js';
-import { IAppendPrepend, IById, IQuery } from './mixin-types.js';
-import { ShadowConfig, Wrapped } from './types.js';
-export interface JJE<T extends Element> extends IQuery, IAppendPrepend {
-}
+import { ShadowConfig } from './types.js';
+import { JJNx } from './JJNx.js';
 /**
  * Wraps a DOM Element (which is a descendant of Node).
  *
@@ -13,7 +10,7 @@ export interface JJE<T extends Element> extends IQuery, IAppendPrepend {
  *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element | Element}
  */
-export declare class JJE<T extends Element = Element> extends JJN<T> implements IById {
+export declare class JJE<T extends Element = Element> extends JJNx<T> {
     /**
      * Creates a JJE instance from an Element reference.
      *
@@ -33,23 +30,12 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      * @throws {TypeError} If `ref` is not an Element.
      */
     constructor(ref: T);
-    /**
-     * 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: string, throwIfNotFound?: boolean): Wrapped | null;
     /**
      * 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: string): string | null;
@@ -58,46 +44,40 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      *
      * @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: string): boolean;
     /**
-     * Sets the value of an attribute.
+     * Sets one or more attributes on the Element.
      *
-     * @param name - The name of the attribute.
-     * @param value - The value to set.
-     * @returns This instance for chaining.
+     * @example
+     * ```ts
+     * el.setAttr('id', 'my-id')  // Single attribute
+     * el.setAttr({ id: 'my-id', class: 'my-class' })  // Multiple attributes
+     * el.setAttr('x', 50)  // Numbers are automatically converted
+     * ```
+     *
+     * @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: string): this;
+    setAttr(name: string, value: any): this;
+    setAttr(obj: Record<string, any>): this;
     /**
-     * Sets multiple attributes at once.
+     * Removes one or more attributes from the Element.
      *
      * @example
      * ```ts
-     * el.setAttrs({ id: 'my-id', class: 'my-class' })
+     * el.rmAttr('disabled')  // Remove single
+     * el.rmAttr('hidden', 'aria-hidden')  // Remove multiple
      * ```
      *
-     * @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: Record<string, string>): this;
-    /**
-     * Removes an attribute.
-     *
-     * @param name - The name of the attribute 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}
      */
-    rmAttr(name: string): this;
-    /**
-     * Removes multiple attributes.
-     *
-     * @param names - The names of the attributes to remove.
-     * @returns This instance for chaining.
-     */
-    rmAttrs(...names: string[]): this;
+    rmAttr(...names: string[]): this;
     /**
      * Gets the value of an ARIA attribute.
      *
@@ -111,6 +91,7 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      *
      * @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: string): string | null;
@@ -119,28 +100,37 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      *
      * @param name - The ARIA attribute suffix.
      * @returns `true` if the attribute exists.
+     * @throws {TypeError} If `name` is not a string.
      */
     hasAria(name: string): boolean;
     /**
-     * Sets an ARIA attribute.
+     * Sets one or more ARIA attributes on the Element.
      *
      * @example
      * ```ts
-     * el.setAria('hidden', 'true') // sets aria-hidden="true"
+     * el.setAria('hidden', 'true')  // Single: sets aria-hidden="true"
+     * el.setAria({ label: 'Close', hidden: 'false' })  // Multiple
+     * el.setAria('level', 2)  // Numbers are automatically converted
      * ```
      *
-     * @param name - The ARIA attribute suffix.
-     * @param value - The value to set.
-     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes | ARIA Attributes}
      */
-    setAria(name: string, value: string): this;
+    setAria(name: string, value: any): this;
+    setAria(obj: Record<string, any>): this;
     /**
-     * Removes an ARIA attribute.
+     * Removes one or more ARIA attributes from the Element.
      *
-     * @param name - The ARIA attribute suffix.
+     * @example
+     * ```ts
+     * el.rmAria('hidden')  // Remove single
+     * el.rmAria('label', 'hidden')  // Remove multiple
+     * ```
+     *
+     * @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: string): this;
+    rmAria(...names: string[]): this;
     /**
      * Gets the class attribute.
      *
@@ -149,54 +139,75 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      */
     getClass(): string | null;
     /**
-     * Sets the class attribute.
+     * Sets the class attribute or conditionally adds/removes classes.
+     *
+     * @remarks
+     * - Pass a string to replace the entire class attribute
+     * - Pass an object with class names as keys and boolean values to conditionally add/remove classes
+     * - To remove all classes, pass an empty string: `setClass('')`
+     *
+     * @example
+     * ```ts
+     * el.setClass('btn btn-primary')  // Set classes as string
+     * el.setClass({                   // Conditional classes (Vue.js style)
+     *   'active': true,               // adds 'active'
+     *   'disabled': false,            // removes 'disabled'
+     *   'highlight': isHighlighted    // adds/removes based on condition
+     * })
+     * ```
      *
-     * @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}
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/classList | Element.classList}
      */
     setClass(className: string): this;
+    setClass(classMap: Record<string, boolean | unknown>): this;
     /**
-     * Removes the `class` attribute of the element.
+     * Adds one or more classes to the Element.
      *
-     * @remarks
-     * If you want to remove a few specific class instead of all, use `rmClasses`
-     *
-     * @returns This instance for chaining.
-     */
-    rmClass(): this;
-    /**
-     * 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: string[]): 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: string[]): this;
+    rmClass(...classNames: string[]): 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: string): boolean;
     /**
-     * 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}
      */
@@ -209,18 +220,12 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      *
      * @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: string, newClassName: string): 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: EventListenerOrEventListenerObject): this;
-    /**
-     * Hides the element by setting the `hidden` attribute and `aria-hidden="true"`.
+
+     * 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}
@@ -228,13 +233,13 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      */
     hide(): this;
     /**
-     * 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(): this;
     /**
-     * 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}
@@ -242,54 +247,35 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      */
     disable(): this;
     /**
-     * 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(): this;
     /**
-     * Gets the title attribute.
+     * Gets the inner HTML of the Element.
      *
-     * @returns The title, or null if not set.
-     */
-    getTitle(): string | null;
-    /**
-     * Sets the title attribute.
-     *
-     * @param title - The title to set.
-     * @returns This instance for chaining.
-     */
-    setTitle(title: string): this;
-    /**
-     * Sets the id attribute.
-     *
-     * @param id - The id to set.
-     * @returns This instance for chaining.
-     */
-    setId(id: string): this;
-    /**
-     * Gets the id attribute.
-     *
-     * @returns The id, or null if not set.
-     */
-    getId(): string | null;
-    /**
-     * 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}
      */
     getHTML(): string;
     /**
-     * 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: string): this;
+    setHTML(html?: string | null): 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.
@@ -305,7 +291,7 @@ export declare class JJE<T extends Element = Element> extends JJN<T> implements
      */
     initShadow(mode?: ShadowRootMode, config?: ShadowConfig): 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.
      */