jj 2.2.0 → 2.3.0

package/lib/mixins.d.ts

@@ -0,0 +1,94 @@
+import { JJN } from './JJN.js';
+import { Unwrapped, Wrappable, Wrapped } from './types.js';
+export declare const wrapAll: typeof JJN.wrapAll, unwrapAll: typeof JJN.unwrapAll;
+/**
+ * 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.
+ */
+export declare function 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.
+ */
+export declare function unwrap(obj: Wrappable): Unwrapped;
+/**
+ * Finds an element by ID in the document.
+ *
+ * @example
+ * ```ts
+ * const el = byId('my-id')
+ * ```
+ *
+ * @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.
+ * @throws {TypeError} If the element is not found and throwIfNotFound is true.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | Document.getElementById}
+ */
+export declare function byId(id: string, throwIfNotFound?: boolean): Wrapped | null;
+/**
+ * Finds elements by class name in the document.
+ *
+ * @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/Document/getElementsByClassName | Document.getElementsByClassName}
+ */
+export declare function byClass(className: string): Wrapped[];
+/**
+ * Finds the first element matching a selector in the document.
+ *
+ * @example
+ * ```ts
+ * const btn = query('.submit-btn')
+ * ```
+ *
+ * @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 not found and throwIfNotFound is true.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector | Document.querySelector}
+ */
+export declare function query(selector: string, throwIfNotFound?: boolean): Wrapped | null;
+/**
+ * Finds all elements matching a selector in the document.
+ *
+ * @example
+ * ```ts
+ * const inputs = queryAll('input[type="text"]')
+ * ```
+ *
+ * @param selector - The CSS selector.
+ * @returns An array of wrapped elements.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll | Document.querySelectorAll}
+ */
+export declare function queryAll(selector: string): Wrapped[];

package/lib/mixins.js

@@ -0,0 +1,359 @@
+import { hasProp, isA, isObj, isStr } from 'jty';
+import { JJHE } from './JJHE.js';
+import { JJE } from './JJE.js';
+import { JJDF } from './JJDF.js';
+import { JJSR } from './JJSR.js';
+import { JJT } from './JJT.js';
+import { JJN } from './JJN.js';
+import { JJD } from './JJD.js';
+import { JJSE } from './JJSE.js';
+export const { wrapAll, unwrapAll } = JJN;
+/**
+ * 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.
+ */
+export function wrap(raw) {
+    if (isStr(raw)) {
+        return JJT.from(document.createTextNode(raw));
+    }
+    if (!isObj(raw)) {
+        throw new TypeError(`Expected an object to wrap. Got ${raw} (${typeof raw})`);
+    }
+    if (isA(raw, JJN)) {
+        return raw;
+    }
+    if (isA(raw, HTMLElement)) {
+        return JJHE.from(raw);
+    }
+    if (isA(raw, SVGElement)) {
+        return JJSE.from(raw);
+    }
+    if (isA(raw, Element)) {
+        return JJE.from(raw);
+    }
+    if (isA(raw, ShadowRoot)) {
+        return JJSR.from(raw);
+    }
+    if (isA(raw, DocumentFragment)) {
+        return JJDF.from(raw);
+    }
+    if (isA(raw, Document)) {
+        return JJD.from(raw);
+    }
+    if (isA(raw, Text)) {
+        return JJT.from(raw);
+    }
+    if (isA(raw, Node)) {
+        return JJN.from(raw);
+    }
+    throw new TypeError(`Expected a Node to wrap. Got ${raw} (${typeof raw})`);
+}
+/**
+ * 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.
+ */
+export function unwrap(obj) {
+    if (isStr(obj)) {
+        return document.createTextNode(obj);
+    }
+    if (!isObj(obj)) {
+        throw new TypeError(`Expected an object. Got ${obj} (${typeof obj})`);
+    }
+    if (isA(obj, Node)) {
+        return obj;
+    }
+    if (isA(obj, JJN)) {
+        return obj.ref;
+    }
+    throw new TypeError(`Could not unwrap ${obj} (${typeof obj})`);
+}
+/**
+ * Finds an element by ID in the document.
+ *
+ * @example
+ * ```ts
+ * const el = byId('my-id')
+ * ```
+ *
+ * @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.
+ * @throws {TypeError} If the element is not found and throwIfNotFound is true.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | Document.getElementById}
+ */
+export 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;
+}
+/**
+ * Finds elements by class name in the document.
+ *
+ * @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/Document/getElementsByClassName | Document.getElementsByClassName}
+ */
+export function byClass(className) {
+    return wrapAll(document.getElementsByClassName(className));
+}
+/**
+ * Finds the first element matching a selector in the document.
+ *
+ * @example
+ * ```ts
+ * const btn = query('.submit-btn')
+ * ```
+ *
+ * @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 not found and throwIfNotFound is true.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector | Document.querySelector}
+ */
+export 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;
+}
+/**
+ * Finds all elements matching a selector in the document.
+ *
+ * @example
+ * ```ts
+ * const inputs = queryAll('input[type="text"]')
+ * ```
+ *
+ * @param selector - The CSS selector.
+ * @returns An array of wrapped elements.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll | Document.querySelectorAll}
+ */
+export function queryAll(selector) {
+    return wrapAll(document.querySelectorAll(selector));
+}
+const 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;
+    },
+};
+const 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'))
+     * ```
+     *
+     * @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);
+        this.ref.append(...nodes);
+        return this;
+    },
+    /**
+     * Prepends children to this node using native prepend.
+     *
+     * @example
+     * ```ts
+     * div.prepend(h('span', null, 'first'))
+     * ```
+     *
+     * @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);
+        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.replaceChildren(h('p', null, 'New Content'))
+     * ```
+     *
+     * @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}
+     */
+    replaceChildren(...children) {
+        const nodes = unwrapAll(children);
+        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.replaceChildren}
+     */
+    empty() {
+        this.replaceChildren();
+        return this;
+    },
+};
+const 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;
+JJN.unwrap = unwrap;
+assignPrototype(JJE, EDDF);
+assignPrototype(JJD, DDF, EDDF);
+assignPrototype(JJDF, DDF, EDDF);
+assignPrototype(JJHE, HESE);
+assignPrototype(JJSE, HESE);
+//# sourceMappingURL=mixins.js.map

package/lib/mixins.js.map

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

package/lib/types.d.ts

@@ -0,0 +1,77 @@
+import type { JJD } from './JJD.js';
+import type { JJDF } from './JJDF.js';
+import type { JJE } from './JJE.js';
+import type { JJHE } from './JJHE.js';
+import type { JJN } from './JJN.js';
+import type { JJSE } from './JJSE.js';
+import type { JJSR } from './JJSR.js';
+import type { JJT } from './JJT.js';
+/**
+ * Represents any value that can be wrapped by the library.
+ * Can be a native Node, a string (which becomes a Text node), or an existing JJ wrapper.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node | Node}
+ */
+export type Wrappable = string | Node | JJN;
+/**
+ * Union type of all possible JJ wrapper classes.
+ */
+export type Wrapped = JJN | JJT | JJE | JJHE | JJSE | JJD | JJDF | JJSR;
+/**
+ * Union type of all native DOM nodes that correspond to JJ wrappers.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Node | Node}
+ */
+export type Unwrapped = Node | Text | Element | HTMLElement | SVGElement | Document | DocumentFragment | ShadowRoot;
+/**
+ * Represents a resource that can be a direct value, a Promise, or a function returning either.
+ * Used for lazy loading or dynamic generation.
+ *
+ * @example
+ * ```ts
+ * type MyConfig = JJResource<string>
+ * const c1: MyConfig = 'value'
+ * const c2: MyConfig = Promise.resolve('value')
+ * const c3: MyConfig = () => 'value'
+ * const c4: MyConfig = async () => 'value'
+ * ```
+ */
+export type JJResource<T> = T | Promise<T> | (() => T | Promise<T>);
+/**
+ * Configuration for the component's template.
+ * Can be an HTML string, a JJHE instance, or a raw HTMLElement.
+ *
+ * @example
+ * ```ts
+ * const t1: JJTemplateConfig = '<div>Hello</div>'
+ * const t2: JJTemplateConfig = fetchHtml('./template.html')
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML | Element.innerHTML}
+ */
+export type JJTemplateConfig = JJResource<string | JJHE | HTMLElement>;
+/**
+ * Configuration for the component's styles.
+ * Can be a CSS string or a CSSStyleSheet.
+ *
+ * @example
+ * ```ts
+ * const s1: JJStyleConfig = 'p { color: red; }'
+ * const s2: JJStyleConfig = fetchCss('./style.css')
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet | CSSStyleSheet}
+ */
+export type JJStyleConfig = JJResource<string | CSSStyleSheet>;
+/**
+ * Configuration for one or more style resources.
+ */
+export type JJStylesConfig = JJStyleConfig | JJStyleConfig[];
+/**
+ * Configuration for initializing a shadowRoot
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets | ShadowRoot.adoptedStyleSheets}
+ */
+export interface ShadowConfig {
+    /** Optional HTML content to set in the shadow root */
+    template?: string;
+    /** Optional CSSStyleSheets to adopt in the shadow root */
+    styles?: CSSStyleSheet[];
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/lib/util.d.ts

@@ -1,8 +1,96 @@
-/** Used to Give the UI a moment to update */
+/**
+ * Returns the file extension
+ *
+ * @remarks
+ * This convenience function is primarily used to guess the 'as' attribute of
+ * a link preload/prefetch behind the scene.
+ *
+ * @example
+ * ```ts
+ * fileExt('file.txt') // => 'txt'
+ * fileExt('https://www.alexewerlof.com/path/to/file.js') // => 'js'
+ * ```
+ *
+ * @param path - absolute, relative, or URL path to a file
+ * @returns the extension name in lowercase and without any dot prefix
+ * @throws {TypeError} If path is not a string.
+ */
+export declare function fileExt(path: string): string;
+/**
+ * Returns a promise that resolves before the next repaint.
+ *
+ * @remarks
+ * Used to give the UI a moment to update.
+ *
+ * @example
+ * ```ts
+ * await nextAnimationFrame()
+ * ```
+ *
+ * @returns A promise that resolves with the timestamp.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame | requestAnimationFrame}
+ */
 export declare function nextAnimationFrame(): Promise<number>;
+/**
+ * Returns a promise that resolves after the specified delay.
+ *
+ * @remarks
+ * Uses `setTimeout` to delay execution. When used with 0ms, it defers
+ * execution to the next macro-task, allowing the event loop to cycle.
+ *
+ * @example
+ * ```ts
+ * await sleep(100)
+ * await sleep() // equivalent to setTimeout(..., 0)
+ * ```
+ *
+ * @param ms - The delay in milliseconds. Defaults to 0.
+ * @returns A promise that resolves after the delay.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/setTimeout | setTimeout}
+ */
+export declare function sleep(ms?: number): Promise<void>;
+/**
+ * Adds an event listener to a target.
+ *
+ * @example
+ * ```ts
+ * on(window, 'resize', () => console.log('resized'))
+ * ```
+ *
+ * @param target - The event target.
+ * @param eventName - The name of the event.
+ * @param handler - The event handler.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener | EventTarget.addEventListener}
+ */
 export declare function on(target: EventTarget, eventName: string, handler: EventListenerOrEventListenerObject): void;
+/**
+ * Removes an event listener from a target.
+ *
+ * @example
+ * ```ts
+ * off(window, 'resize', handler)
+ * ```
+ *
+ * @param target - The event target.
+ * @param eventName - The name of the event.
+ * @param handler - The event handler.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener | EventTarget.removeEventListener}
+ */
 export declare function off(target: EventTarget, eventName: string, handler: EventListenerOrEventListenerObject): void;
 /**
- * Converts a CSS string to a CSSStyleSheet (suitable for attaching to ShadowRoot for example)
+ * Converts a CSS string to a CSSStyleSheet.
+ *
+ * @remarks
+ * Suitable for attaching to ShadowRoot via `adoptedStyleSheets`.
+ *
+ * @example
+ * ```ts
+ * const sheet = await cssToStyle('p { color: red; }')
+ * shadowRoot.adoptedStyleSheets = [sheet]
+ * ```
+ *
+ * @param css - The CSS string.
+ * @returns A promise resolving to the created CSSStyleSheet.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/replace | CSSStyleSheet.replace}
  */
 export declare function cssToStyle(css: string): Promise<CSSStyleSheet>;