jj 2.2.0 → 2.4.0

package/lib/JJHE.js

@@ -0,0 +1,164 @@
+import { hasProp, isA, isStr } from 'jty';
+import { JJE } from './JJE.js';
+import { JJN } from './JJN.js';
+/**
+ * Wraps a DOM HTMLElement (which is a descendant of Element).
+ *
+ * @remarks
+ * This class extends `JJE` to provide specific functionality for HTML elements,
+ * such as access to `dataset`, `innerText`, and form values.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement | HTMLElement}
+ */
+export class JJHE extends JJE {
+    /**
+     * Creates a JJHE instance from an HTMLElement reference.
+     *
+     * @example
+     * ```ts
+     * const el = JJHE.from(document.getElementById('my-id'))
+     * ```
+     *
+     * @param ref - The HTMLElement.
+     * @returns A new JJHE instance.
+     */
+    static from(ref) {
+        return new JJHE(ref);
+    }
+    /**
+     * Creates a JJHE instance from a tag name.
+     *
+     * @example
+     * ```ts
+     * const div = JJHE.fromTag('div')
+     * const input = JJHE.fromTag('input', { is: 'custom-input' })
+     * ```
+     *
+     * @param tagName - The tag name.
+     * @param options - Element creation options.
+     * @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 fromTag(tagName, options) {
+        if (!isStr(tagName)) {
+            throw new TypeError(`Expected a string for tagName. Got: ${tagName} (${typeof tagName})`);
+        }
+        return new JJHE(document.createElement(tagName, options));
+    }
+    /**
+     * Creates an instance of JJHE.
+     *
+     * @param ref - The HTMLElement to wrap.
+     * @throws {TypeError} If `ref` is not an HTMLElement.
+     */
+    constructor(ref) {
+        if (!isA(ref, HTMLElement)) {
+            throw new TypeError(`Expected an HTMLElement. Got ${ref} (${typeof ref})`);
+        }
+        super(ref);
+    }
+    /**
+     * Gets the value property of the element (e.g. for inputs).
+     *
+     * @returns The value.
+     * @throws {Error} If the element 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');
+        }
+        return this.ref.value;
+    }
+    /**
+     * Sets the value property of the element.
+     *
+     * @example
+     * ```ts
+     * input.setValue('new value')
+     * ```
+     *
+     * @param value - The value to set.
+     * @returns This instance for chaining.
+     * @throws {Error} If the element 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');
+        }
+        this.ref.value = value;
+        return this;
+    }
+    /**
+     * Focuses the element.
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus | HTMLElement.focus}
+     */
+    focus() {
+        this.ref.focus();
+        return this;
+    }
+    /**
+     * Clicks the element.
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click | HTMLElement.click}
+     */
+    click() {
+        this.ref.click();
+        return this;
+    }
+    /**
+     * Gets the inner text of the element.
+     *
+     * @returns The inner text.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText | HTMLElement.innerText}
+     */
+    getText() {
+        return this.ref.innerText;
+    }
+    /**
+     * Sets the inner text of the element.
+     *
+     * @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}
+     */
+    setText(text) {
+        this.ref.innerText = text;
+        return this;
+    }
+    /**
+     * Finds the first element matching a selector within this element's context.
+     *
+     * @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}
+     */
+    query(selector, throwIfNotFound = true) {
+        const el = this.ref.querySelector(selector);
+        if (el) {
+            return JJN.wrap(el);
+        }
+        if (throwIfNotFound) {
+            throw new TypeError(`Element with selector ${selector} not found`);
+        }
+        return null;
+    }
+    /**
+     * Finds all elements matching a selector within this element's context.
+     *
+     * @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}
+     */
+    queryAll(selector) {
+        return JJN.wrapAll(this.ref.querySelectorAll(selector));
+    }
+}
+//# sourceMappingURL=JJHE.js.map

package/lib/JJHE.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JJHE.js","sourceRoot":"","sources":["../src/JJHE.ts"],"names":[],"mappings":"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"}

package/lib/JJN.d.ts

@@ -0,0 +1,234 @@
+import { Unwrapped, Wrappable, Wrapped } from './types.js';
+import { IAppendPrepend } from './mixin-types.js';
+/**
+ * Wraps a DOM Node.
+ *
+ * @remarks
+ * This is the base class for all JJ wrappers. It provides common functionality for DOM manipulation,
+ * traversal, and event handling.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node | Node}
+ */
+export declare class JJN<T extends Node = Node> implements IAppendPrepend {
+    #private;
+    /**
+     * Creates a JJN instance from a Node reference.
+     *
+     * @example
+     * ```ts
+     * const node = JJN.from(document.createTextNode('hello'))
+     * ```
+     *
+     * @param node - The Node instance.
+     * @returns A new JJN instance.
+     */
+    static from(node: Node): JJN;
+    /**
+     * Checks if a value can be passed to the `wrap()` or `unwrap()` function.
+     *
+     * @remarks
+     * 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)
+     */
+    static isWrapable(x: unknown): x is Wrappable;
+    /**
+     * Wraps a native DOM node or string into the most specific JJ wrapper available.
+     *
+     * @remarks
+     * This function acts as a factory, inspecting the input type and returning the appropriate
+     * subclass of `JJN` (e.g., `JJHE` for `HTMLElement`, `JJT` for `Text`).
+     *
+     * @example
+     * ```ts
+     * const bodyWrapper = JJN.wrap(document.body) // Returns JJHE
+     * const textWrapper = JJN.wrap('Hello') // Returns JJT wrapping a new Text node
+     * ```
+     *
+     * @param raw - The object to wrap. If it's already Wrapped, it'll be returned without any change. We don't double-wrap or clone it.
+     * @returns The most granular Wrapped subclass instance. If the input is already wrapped, it'll be returned as is without cloning.
+     * @throws {TypeError} If the input is not a Node, string, or JJ wrapper.
+     */
+    static wrap(raw: Wrappable): Wrapped;
+    /**
+     * Extracts the underlying native DOM node from a wrapper.
+     *
+     * @remarks
+     * If the input is already a native Node, it is returned as is.
+     * If the input is a string, a new Text node is created and returned.
+     *
+     * @example
+     * ```ts
+     * const rawElement = JJN.unwrap(myJJHE) // Returns HTMLElement
+     * ```
+     *
+     * @param obj - The object to unwrap.
+     * @returns The underlying DOM node.
+     * @throws {TypeError} If the input cannot be unwrapped.
+     */
+    static unwrap(obj: Wrappable): Unwrapped;
+    /**
+     * Wraps an iterable object (e.g. an array of wrapped or DOM elements).
+     *
+     * @example
+     * ```ts
+     * const wrappedList = JJN.wrapAll(document.querySelectorAll('div'))
+     * ```
+     *
+     * @param iterable - The iterable to wrap.
+     * @returns An array of wrapped instances.
+     */
+    static wrapAll(iterable: Iterable<Wrappable>): Wrapped[];
+    /**
+     * Unwraps an iterable object (e.g. an array or HTMLCollection).
+     *
+     * @example
+     * ```ts
+     * const nodes = JJN.unwrapAll(wrappedList)
+     * ```
+     *
+     * @param iterable - The iterable to unwrap.
+     * @returns An array of native DOM nodes.
+     */
+    static unwrapAll(iterable: Iterable<Wrappable>): Unwrapped[];
+    /**
+     * Creates an instance of JJN.
+     *
+     * @param ref - The Node to wrap.
+     * @throws {TypeError} If `ref` is not a Node.
+     */
+    constructor(ref: T);
+    /**
+     * Gets the underlying DOM Node.
+     */
+    get ref(): T;
+    /**
+     * Clones the node.
+     *
+     * @param deep - If true, clones the subtree.
+     * @returns A new wrapped instance of the clone.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/cloneNode | Node.cloneNode}
+     */
+    clone(deep?: boolean): Wrapped;
+    /**
+     * Appends 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 append (Nodes, strings, or Wrappers).
+     * @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}
+     */
+    append(...children: Wrappable[]): this;
+    /**
+     * Maps an array to children and appends them.
+     *
+     * @example
+     * ```ts
+     * list.mapAppend(['a', 'b'], item => h('li', null, item))
+     * ```
+     *
+     * @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: Wrappable[], mapFn: (item: Wrappable) => Wrappable): this;
+    /**
+     * 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}
+     */
+    prepend(...children: Wrappable[]): this;
+    /**
+     * Maps an array to children and prepends them.
+     *
+     * @example
+     * ```ts
+     * list.mapPrepend(['a', 'b'], item => JJHE.fromTag('li').setText(item))
+     * ```
+     *
+     * @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.
+     */
+    mapPrepend(array: Wrappable[], mapFn: (item: Wrappable) => Wrappable): this;
+    /**
+     * Replaces the existing children of this node with a specified new set of children.
+     *
+     * @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: Wrappable[]): this;
+    /**
+     * Adds an event listener.
+     *
+     * @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/addEventListener | EventTarget.addEventListener}
+     */
+    on(eventName: string, handler: EventListenerOrEventListenerObject): this;
+    /**
+     * Removes an event listener.
+     *
+     * @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: string, handler: EventListenerOrEventListenerObject): this;
+    /**
+     * Removes this node from the DOM.
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild | Node.removeChild}
+     */
+    rm(): this;
+    /**
+     * Removes all children from this node.
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.replaceChildren}
+     */
+    empty(): this;
+    /**
+     * Runs a function in the context of this JJN instance.
+     *
+     * @example
+     * ```ts
+     * div.run(function() {
+     *   this.addClass('active')
+     *   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 JJN instance.
+     * @param args - Arguments to pass to the function.
+     * @returns The return value of the function.
+     */
+    run<R, Args extends any[]>(fn: (this: this, ...args: Args) => R, ...args: Args): R;
+}