jj 2.4.0 → 2.6.0

package/lib/bundle.min.d.cts

@@ -0,0 +1,1782 @@
+/**
+ * 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.
+ */
+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}
+ */
+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}
+ */
+declare function sleep(ms?: number): Promise<void>;
+/**
+ * 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}
+ */
+declare function cssToStyle(css: string): Promise<CSSStyleSheet>;
+
+/**
+ * Converts a PascalCase, camelCase, or snake_case string to kebab-case.
+ *
+ * @remarks
+ * This function is useful for converting JavaScript property names to CSS or HTML attribute names.
+ * It strictly validates the input to contain only alphanumeric characters and underscores.
+ *
+ * @example
+ * ```ts
+ * pas2keb('backgroundColor') // 'background-color'
+ * pas2keb('MyComponent') // 'my-component'
+ * pas2keb('user_id') // 'user-id'
+ * ```
+ *
+ * @param str - The string to convert.
+ * @returns The kebab-case string.
+ * @throws {TypeError} If `str` is not a string or contains invalid characters (anything other than `/[a-zA-Z0-9_]/`).
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace | String.prototype.replace}
+ */
+declare function pas2keb(str: string): string;
+/**
+ * Converts a kebab-case string to PascalCase.
+ *
+ * @remarks
+ * This function splits the string by hyphens and capitalizes the first letter of each segment.
+ * It handles multiple hyphens by ignoring empty segments.
+ *
+ * @example
+ * ```ts
+ * keb2pas('background-color') // 'BackgroundColor'
+ * keb2pas('my-component') // 'MyComponent'
+ * keb2pas('multi--dash') // 'MultiDash'
+ * ```
+ *
+ * @param str - The string to convert.
+ * @returns The PascalCase string.
+ * @throws {TypeError} If `str` is not a string.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split | String.prototype.split}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map | Array.prototype.map}
+ */
+declare function keb2pas(str: string): string;
+/**
+ * Converts a kebab-case string to camelCase.
+ *
+ * @remarks
+ * This function is primarily useful for converting attributes to JavaScript property names.
+ * Leading and trailing hyphens are removed before conversion.
+ *
+ * @example
+ * ```ts
+ * keb2cam('background-color') // 'backgroundColor'
+ * keb2cam('-webkit-transform') // 'webkitTransform'
+ * ```
+ *
+ * @param str - The string to convert.
+ * @returns The camelCase string.
+ * @throws {TypeError} If `str` is not a string.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace | String.prototype.replace}
+ */
+declare function keb2cam(str: string): string;
+
+/**
+ * Wraps a DOM EventTarget.
+ *
+ * @remarks
+ * This is the base class for all JJ wrappers that wrap an EventTarget.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget | EventTarget}
+ */
+declare class JJET<T extends EventTarget = EventTarget> {
+    #private;
+    static from(ref: EventTarget): JJET<EventTarget>;
+    /**
+     * Creates a JJET instance.
+     *
+     * @param ref - The EventTarget to wrap.
+     * @throws {TypeError} If `ref` is not an EventTarget.
+     */
+    constructor(ref: T);
+    /**
+     * Gets the underlying DOM object.
+     */
+    get ref(): T;
+    /**
+     * Adds an event listener.
+     *
+     * @remarks
+     * The handler is automatically bound to this JJET instance, so `this` inside the handler
+     * refers to the JJET instance, not the DOM element. To access the DOM element, use `this.ref`.
+     *
+     * @example
+     * ```ts
+     * JJET.from(window).on('resize', function() {
+     *   console.log(this) // JJET instance
+     *   console.log(this.ref) // window object
+     * })
+     * ```
+     * @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: string, handler: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions): this;
+    /**
+     * Removes an event listener.
+     *
+     * @remarks
+     * Pass the same handler reference that was used in `on()` to properly remove the listener.
+     *
+     * @example
+     * ```ts
+     * const handler = function() { console.log(this) }
+     * JJET.from(window).on('resize', handler)
+     * JJET.from(window).off('resize', handler)
+     * ```
+     * @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: string, handler: EventListenerOrEventListenerObject | null, options?: EventListenerOptions | boolean): 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: Event): 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<R, Args extends any[]>(fn: (this: this, ...args: Args) => R, ...args: Args): R;
+}
+
+/**
+ * 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}
+ */
+declare class JJN<T extends Node = Node> extends JJET<T> {
+    /**
+     * 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);
+    /**
+     * 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;
+    /**
+     * Creates a Text node from a string and appends it to this Node.
+     *
+     * @remarks
+     * This method is overridden in JJT to append to the existing text content instead.
+     *
+     * @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/Document/createTextNode | document.createTextNode}
+     */
+    addText(text?: string | null): this;
+}
+
+declare abstract class JJNx<T extends Element | Document | DocumentFragment> extends JJN<T> {
+    /**
+     * Finds the first element matching a selector within this Element.
+     *
+     * @example
+     * ```ts
+     * const span = el.find('span')  // Returns null if not found
+     * const span = el.find('span', true)  // Throws if not found
+     * ```
+     *
+     * @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}
+     */
+    find(selector: string, required?: boolean): Wrapped | null;
+    /**
+     * Finds all elements matching a selector within this Element.
+     *
+     * @example
+     * ```ts
+     * const items = el.findAll('li')
+     * ```
+     *
+     * @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}
+     */
+    findAll(selector: string): Wrapped[];
+    /**
+     * Appends children to this Element.
+     *
+     * @example
+     * ```ts
+     * el.addChild(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 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}
+     */
+    addChild(...children: Wrappable[]): this;
+    /**
+     * Prepends children to this Element.
+     *
+     * @example
+     * ```ts
+     * el.preChild(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 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}
+     */
+    preChild(...children: Wrappable[]): this;
+    /**
+     * Maps an array to children and appends them.
+     *
+     * @example
+     * ```ts
+     * node.addChildMap(['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.
+     */
+    addChildMap(array: Wrappable[], mapFn: (item: Wrappable) => Wrappable): this;
+    /**
+     * Maps an array to children and prepends them.
+     *
+     * @example
+     * ```ts
+     * node.preChildMap(['a', 'b'], item => JJHE.create('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.
+     */
+    preChildMap(array: Wrappable[], mapFn: (item: Wrappable) => Wrappable): this;
+    /**
+     * Replaces the existing children of an Element with a specified new set of children.
+     *
+     * @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
+     * el.setChildren(h('p', null, 'New Content'))
+     * ```
+     * @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}
+     */
+    setChildren(...children: Wrappable[]): this;
+    /**
+     * Removes all children from this Element.
+     *
+     * @example
+     * ```ts
+     * el.empty()
+     * ```
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/replaceChildren | Element.setChildren}
+     */
+    empty(): this;
+}
+
+/**
+ * Wraps a DocumentFragment (which is a descendant of Node).
+ *
+ * @remarks
+ * DocumentFragments are lightweight versions of Document that store a segment of a document structure
+ * comprised of nodes just like a standard document. The key difference is that because the document fragment
+ * isn't part of the active document tree structure, changes made to the fragment don't affect the document,
+ * cause reflow, or incur any performance impact that can occur when changes are made.
+ *
+ * @example
+ * ```ts
+ * const frag = JJDF.create()
+ * frag.addChild(
+ *   h('div', null, 'Item 1'),
+ *   h('div', null, 'Item 2'),
+ * )
+ * doc.body.addChild(frag)
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment | DocumentFragment}
+ */
+declare class JJDF<T extends DocumentFragment = DocumentFragment> extends JJNx<T> {
+    /**
+     * Creates a JJDF instance from a DocumentFragment reference.
+     *
+     * @example
+     * ```ts
+     * const frag = JJDF.from(myFrag)
+     * ```
+     *
+     *
+     * @param ref - The DocumentFragment instance.
+     * @returns A new JJDF instance.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment | DocumentFragment}
+     */
+    static from(ref: DocumentFragment): JJDF;
+    /**
+     * Creates a new empty JJDF instance (wraps a new DocumentFragment).
+     *
+     * @example
+     * ```ts
+     * const frag = JJDF.create()
+     * ```
+     *
+     * @returns A new JJDF instance.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createDocumentFragment | document.createDocumentFragment}
+     */
+    static create(): JJDF<DocumentFragment>;
+    /**
+     * Creates an instance of JJDF.
+     *
+     * @param ref - The DocumentFragment instance to wrap.
+     * @throws {TypeError} If `ref` is not a DocumentFragment.
+     */
+    constructor(ref: T);
+}
+
+/**
+ * Wraps a DOM ShadowRoot (which is a descendant of DocumentFragment).
+ *
+ * @remarks
+ * The ShadowRoot interface of the Shadow DOM API is the root node of a DOM subtree
+ * that is rendered separately from a document's main DOM tree.
+ *
+ * ShadowRoot inherits DocumentFragment and therefore has access to all its methods
+ * most importantly `find`, and `findAll` which come handy to access and
+ * update its children.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot | ShadowRoot}
+ */
+declare class JJSR<T extends ShadowRoot = ShadowRoot> extends JJDF<T> {
+    /**
+     * Creates a JJSR instance from a ShadowRoot reference.
+     *
+     * @example
+     * ```ts
+     * const shadow = JJSR.from(element.shadowRoot)
+     * ```
+     *
+     * @param shadowRoot - The ShadowRoot instance.
+     * @returns A new JJSR instance.
+     */
+    static from(shadowRoot: ShadowRoot): JJSR<ShadowRoot>;
+    /**
+     * Creates an instance of JJSR.
+     *
+     * @param shadowRoot - The ShadowRoot to wrap.
+     * @throws {TypeError} If `shadowRoot` is not a ShadowRoot.
+     */
+    constructor(shadowRoot: T);
+    /**
+     * 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}
+     */
+    getHTML(): string;
+    /**
+     * Sets the inner HTML of the ShadowRoot.
+     *
+     * @example
+     * ```ts
+     * shadow.setHTML('<p>Hello</p>', true)
+     * ```
+     *
+     * @param html - The HTML string to set, or null/undefined to clear.
+     * @param unsafe - explicit opt-in to set innerHTML. must be true if html is provided.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML | Element.innerHTML}
+     */
+    setHTML(html: string | null | undefined, unsafe?: boolean): this;
+    /**
+     * Adds constructed stylesheets to the ShadowRoot.
+     *
+     * @example
+     * ```ts
+     * const sheet = new CSSStyleSheet()
+     * sheet.replaceSync('p { color: red; }')
+     * shadow.addStyleSheets(sheet)
+     * ```
+     *
+     * @param styleSheets - The stylesheets to add.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets | ShadowRoot.adoptedStyleSheets}
+     */
+    addStyleSheets(...styleSheets: CSSStyleSheet[]): this;
+}
+
+/**
+ * Wraps a DOM Element (which is a descendant of Node).
+ *
+ * @remarks
+ * This class provides a wrapper around the native `Element` interface, adding fluent API methods
+ * for attribute manipulation, class handling, and event binding.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element | Element}
+ */
+declare class JJE<T extends Element = Element> extends JJNx<T> {
+    /**
+     * Creates a JJE instance from an Element reference.
+     *
+     * @example
+     * ```ts
+     * const el = JJE.from(document.querySelector('.my-class'))
+     * ```
+     *
+     * @param ref - The Element instance.
+     * @returns A new JJE instance.
+     */
+    static from(ref: Element): JJE;
+    /**
+     * Creates an instance of JJE.
+     *
+     * @param ref - The Element to wrap.
+     * @throws {TypeError} If `ref` is not an Element.
+     */
+    constructor(ref: T);
+    /**
+     * 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;
+    /**
+     * Checks if an attribute exists.
+     *
+     * @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 one or more attributes on the Element.
+     *
+     * @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: any): this;
+    setAttr(obj: Record<string, any>): this;
+    /**
+     * Removes one or more attributes from the Element.
+     *
+     * @example
+     * ```ts
+     * el.rmAttr('disabled')  // Remove single
+     * el.rmAttr('hidden', 'aria-hidden')  // Remove multiple
+     * ```
+     *
+     * @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(...names: string[]): this;
+    /**
+     * Gets the value of an ARIA attribute.
+     *
+     * @remarks
+     * Automatically prepends `aria-` to the name.
+     *
+     * @example
+     * ```ts
+     * el.getAria('label') // gets 'aria-label'
+     * ```
+     *
+     * @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;
+    /**
+     * Checks if an ARIA attribute exists.
+     *
+     * @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 one or more ARIA attributes on the Element.
+     *
+     * @example
+     * ```ts
+     * el.setAria('hidden', 'true')  // Single: sets aria-hidden="true"
+     * el.setAria({ label: 'Close', hidden: 'false' })  // Multiple
+     * el.setAria('level', 2)  // Numbers are automatically converted
+     * ```
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes | ARIA Attributes}
+     */
+    setAria(name: string, value: any): this;
+    setAria(obj: Record<string, any>): this;
+    /**
+     * Removes one or more ARIA attributes from the Element.
+     *
+     * @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(...names: string[]): this;
+    /**
+     * Gets the class attribute.
+     *
+     * @returns The class attribute value, or null if not present.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/className | Element.className}
+     */
+    getClass(): string | null;
+    /**
+     * 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
+     * })
+     * ```
+     *
+     * @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;
+    /**
+     * 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.
+     *
+     * @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}
+     */
+    rmClass(...classNames: string[]): this;
+    /**
+     * 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.
+     *
+     * @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: string): this;
+    /**
+     * Replaces a class with another one
+     *
+     * @remarks
+     * If the `oldClassName` doesn't exist, the `newClassName` isn't added
+     *
+     * @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;
+    /**
+     * Finds the closest ancestor (or self) that matches a CSS selector.
+     *
+     * @remarks
+     * Returns `null` when no matching ancestor is found.
+     *
+     * @example
+     * ```ts
+     * const button = JJE.from(document.querySelector('button'))
+     * const card = button.closest('.card')
+     * if (card) {
+     *     card.addClass('has-action')
+     * }
+     * ```
+     *
+     * @param selector - The CSS selector to search for.
+     * @returns A JJE wrapping the closest match, or null when none exists.
+     * @throws {TypeError} If `selector` is not a string.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/closest | Element.closest}
+     */
+    closest(selector: string): Wrapped | null;
+    /**
+
+     * 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(): this;
+    /**
+     * 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"`.
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled | disabled attribute}
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled | aria-disabled}
+     */
+    disable(): this;
+    /**
+     * Enables the Element by removing the `disabled` and `aria-disabled` attributes.
+     *
+     * @returns This instance for chaining.
+     */
+    enable(): this;
+    /**
+     * 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.
+     *
+     * @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, or null/undefined to clear.
+     * @param unsafe - explicit opt-in to set innerHTML. must be true if html is provided.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML | Element.innerHTML}
+     */
+    setHTML(html: string | null | undefined, unsafe?: boolean): this;
+    /**
+     * 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.
+     * **Note:** You can't attach a shadow root to every type of element. There are some that can't have a
+     * shadow DOM for security reasons (for example `<a>`).
+     *
+     * @param mode - The encapsulation mode ('open' or 'closed'). Defaults to 'open'.
+     * @param config - Optional configuration object containing `template` (HTML string) and `styles` (array of CSSStyleSheet).
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow | Element.attachShadow}
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets | ShadowRoot.adoptedStyleSheets}
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets | Document.adoptedStyleSheets}
+     */
+    initShadow(mode?: ShadowRootMode, config?: ShadowConfig): this;
+    /**
+     * 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.
+     */
+    get shadow(): JJSR<ShadowRoot> | null;
+}
+
+declare abstract class JJEx<T extends HTMLElement | SVGElement> extends JJE<T> {
+    /**
+     * Gets a data attribute from the HTMLElement.
+     *
+     * @example
+     * ```ts
+     * const value = el.getData('my-key')
+     * ```
+     *
+     * @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}
+     */
+    getData(name: string): string | undefined;
+    /**
+     * Checks if a data attribute exists on the HTMLElement.
+     *
+     * @example
+     * ```ts
+     * if (el.hasData('my-key')) {
+     *   // ...
+     * }
+     * ```
+     *
+     * @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: string): boolean;
+    /**
+     * Sets one or more data attributes on the HTMLElement.
+     *
+     * @example
+     * ```ts
+     * el.setData('myKey', 'myValue')  // Single
+     * el.setData({ myKey: 'myValue', otherKey: 'otherValue' })  // Multiple
+     * el.setData('count', 42)  // Numbers are automatically converted
+     * ```
+     *
+     * @throws {TypeError} If arguments are invalid types.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset | HTMLElement.dataset}
+     */
+    setData(name: string, value: any): this;
+    setData(obj: Record<string, any>): 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: string[]): this;
+}
+
+/**
+ * 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}
+ */
+declare class JJHE<T extends HTMLElement = HTMLElement> extends JJEx<T> {
+    /**
+     * 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.
+     */
+    static from<T extends HTMLElement>(ref: T): JJHE<T>;
+    /**
+     * Creates a JJHE instance from a tag name.
+     *
+     * @example
+     * ```ts
+     * const div = JJHE.create('div')
+     * const input = JJHE.create('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 create<K extends keyof HTMLElementTagNameMap>(tagName: K, options?: ElementCreationOptions): JJHE<HTMLElementTagNameMap[K]>;
+    static create(tagName: string, options?: ElementCreationOptions): JJHE;
+    /**
+     * Creates an instance of JJHE.
+     *
+     * @param ref - The HTMLElement to wrap.
+     * @throws {TypeError} If `ref` is not an HTMLElement.
+     */
+    constructor(ref: T);
+    /**
+     * Gets the value property of the HTMLElement (e.g. for inputs).
+     *
+     * @returns The value.
+     * @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(): unknown;
+    /**
+     * 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 HTMLElement does not have a value property.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/value | HTMLInputElement.value}
+     */
+    setValue(value: any): this;
+    /**
+     * Focuses the HTMLElement.
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus | HTMLElement.focus}
+     */
+    focus(): this;
+    /**
+     * Clicks the HTMLElement.
+     *
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click | HTMLElement.click}
+     */
+    click(): this;
+    /**
+     * 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}
+     */
+    getText(): string;
+    /**
+     * 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?: any): this;
+}
+
+/**
+ * Wraps a Document (which is a descendant of Node).
+ *
+ * @remarks
+ * This class provides a wrapper around the native `Document` interface, inheriting
+ * the fluent API capabilities of `JJN`.
+ * It also supports querying (`find`) and manipulation (`addChild`, `preChild`) methods.
+ *
+ * To find elements by class name, use: `doc.find('.my-class')`
+ *
+ * To set the document title, use: `doc.ref.title = 'New Title'`
+ *
+ * @example
+ * ```ts
+ * const doc = JJD.from(document)
+ * doc.on('DOMContentLoaded', () => console.log('Ready'))
+ * doc.ref.title = 'My Page Title'  // Set document title
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document | Document}
+ */
+declare class JJD<T extends Document = Document> extends JJNx<T> {
+    /**
+     * 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: Document): JJD;
+    /**
+     * Creates an instance of JJD.
+     *
+     * @param ref - The Document instance to wrap.
+     * @throws {TypeError} If `ref` is not a Document.
+     */
+    constructor(ref: T);
+    /**
+     * 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(): JJHE<HTMLHeadElement>;
+    /**
+     * 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(): JJHE<HTMLElement>;
+}
+
+/**
+ * Wraps a DOM SVGElement.
+ *
+ * @remarks
+ * This class extends `JJE` to provide specific functionality for SVG elements,
+ * including namespace-aware creation and helper methods for common SVG attributes.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/SVGElement | SVGElement}
+ */
+declare class JJSE<T extends SVGElement = SVGElement> extends JJEx<T> {
+    /**
+     * Creates a JJSE instance from an SVGElement reference.
+     *
+     * @example
+     * ```ts
+     * const svg = JJSE.from(myCircle)
+     * ```
+     *
+     * @param ref - The SVGElement.
+     * @returns A new JJSE instance.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/SVGElement | SVGElement}
+     */
+    static from(ref: SVGElement): JJSE;
+    /**
+     * Creates a JJSE instance from a tag name (in the SVG namespace).
+     *
+     * @remarks
+     * Automatically uses the correct SVG namespace URI: `http://www.w3.org/2000/svg`.
+     *
+     * @example
+     * ```ts
+     * const circle = JJSE.create('circle')
+     * ```
+     *
+     * @param tagName - The tag name.
+     * @param options - Element creation options.
+     * @returns A new JJSE instance.
+     * @throws {TypeError} If `tagName` is not a string.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS | document.createElementNS}
+     */
+    static create(tagName: string, options?: ElementCreationOptions): JJSE;
+    /**
+     * Creates an instance of JJSE.
+     *
+     * @param ref - The SVGElement to wrap.
+     * @throws {TypeError} If `ref` is not an SVGElement.
+     */
+    constructor(ref: T);
+    /**
+     * 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}
+     */
+    getText(): string;
+    /**
+     * 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.
+     *
+     * @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?: any): this;
+    /**
+     * Sets the fill attribute.
+     *
+     * @param value - The fill color/value.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill | fill}
+     */
+    setFill(value: string): this;
+    /**
+     * Sets the stroke attribute.
+     *
+     * @param value - The stroke color/value.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke | stroke}
+     */
+    setStroke(value: string): this;
+    /**
+     * Sets the stroke-width attribute.
+     *
+     * @param value - The width.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-width | stroke-width}
+     */
+    setStrokeWidth(value: string | number): this;
+    /**
+     * Sets the viewBox attribute.
+     *
+     * @example
+     * ```ts
+     * svg.setViewBox(0, 0, 100, 100)
+     * svg.setViewBox('0 0 100 100')
+     * ```
+     *
+     * @param p1 - Min-x or string/array value.
+     * @param p2 - Min-y.
+     * @param p3 - Width.
+     * @param p4 - Height.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox | viewBox}
+     */
+    setViewBox(p1: string | (string | number)[] | number, p2?: number, p3?: number, p4?: number): this;
+    /**
+     * Sets the width attribute.
+     *
+     * @param value - The width.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/width | width}
+     */
+    setWidth(value: string | number): this;
+    /**
+     * Sets the height attribute.
+     *
+     * @param value - The height.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/height | height}
+     */
+    setHeight(value: string | number): this;
+    /**
+     * Sets the d attribute (path data).
+     *
+     * @param value - The path data string or array of segments.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d | d}
+     */
+    setD(value: string | (string | number)[]): this;
+    /**
+     * Sets the transform attribute.
+     *
+     * @param value - The transform string.
+     * @returns This instance for chaining.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform | transform}
+     */
+    setTransform(value: string): this;
+}
+
+/**
+ * Wraps a DOM Text Node.
+ *
+ * @remarks
+ * The Text interface represents the textual content of Element or Attr.
+ * If an element has no markup within its content, it has a single child implementing Text
+ * that contains the element's text.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Text | Text}
+ */
+declare class JJT<T extends Text = Text> extends JJN<Text> {
+    /**
+     * 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: Text): JJT;
+    static fromStr(text: string): JJT;
+    /**
+     * 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: T);
+    /**
+     * 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(): string;
+    /**
+     * 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?: any): 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?: any): 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(): this;
+}
+
+/**
+ * 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}
+ */
+type Wrappable = string | Node | JJN;
+/**
+ * Union type of all possible JJ wrapper classes.
+ */
+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}
+ */
+type Unwrapped = Node | Text | Element | HTMLElement | SVGElement | Document | DocumentFragment | ShadowRoot;
+/**
+ * Configuration for the component's template.
+ * Can be an HTML string, a JJHE instance, a raw HTMLElement, or a
+ * Promise / factory that yields one of those.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML | Element.innerHTML}
+ * @example
+ * ```ts
+ * const t1: tmplConf = '<div>Hello</div>'
+ * const t2: tmplConf = fetchHtml('./template.html') // Lazy loading
+ * const t3: tmplConf = () => fetchHtml('./template.html') // Lazy loading
+ * const t4: tmplConf = new JJHE(document.createElement('div')) // JJHE instance
+ * const t5: tmplConf = document.createElement('div') // Raw HTMLElement
+ * const t6: tmplConf = await fetchHtml('./template.html') // Eager loading
+ * ```
+ */
+type JJTemplateConfig = string | JJHE | JJDF | HTMLElement | DocumentFragment | Promise<string | JJHE | JJDF | HTMLElement | DocumentFragment> | (() => string | JJHE | JJDF | HTMLElement | DocumentFragment | Promise<string | JJHE | JJDF | HTMLElement | DocumentFragment>);
+/**
+ * Configuration for the component's styles.
+ * Can be a CSS string, a CSSStyleSheet, or a Promise / factory that yields one of those.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet | CSSStyleSheet}
+ * @example
+ * ```ts
+ * const s1: JJStyleConfig = 'p { color: red; }' // simple string
+ * const s2: JJStyleConfig = cssToSheet('p { color: red; }') // Parse string to CSSStyleSheet
+ * const s3: JJStyleConfig = await fetchCss('./style.css') // Eager loading
+ * const s4: JJStyleConfig = fetchCss('./style.css') // Lazy loading
+ * const s5: JJStyleConfig = () => fetchCss('./style.css') // Lazy loading
+ * ```
+ */
+type JJStyleConfig = string | CSSStyleSheet | Promise<string | CSSStyleSheet> | (() => string | CSSStyleSheet | Promise<string | CSSStyleSheet>);
+/**
+ * Configuration for initializing a shadowRoot
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets | ShadowRoot.adoptedStyleSheets}
+ */
+interface ShadowConfig {
+    /** Optional HTML content to set in the shadow root */
+    template?: string | DocumentFragment;
+    /** Optional CSSStyleSheets to adopt in the shadow root */
+    styles?: CSSStyleSheet[];
+}
+
+/**
+ * Hyperscript helper to create JJHE instances.
+ * The `h` function provides a concise way to create DOM wrappers with attributes and children,
+ * similar to hyperscript helpers found in other libraries.
+ *
+ *
+ * @remarks
+ * It returns a `JJHE` instance which wraps the native HTMLElement.
+ *
+ * You may recognize it from other libraries:
+ * - [React](https://react.dev/reference/react/createElement)
+ * - [Vue](https://vuejs.org/guide/extras/render-function)
+ * - [Hyperscript](https://github.com/hyperhype/hyperscript)
+ * - [Angular](https://angular.dev/guide/components/programmatic-rendering)
+ * - [Lit](https://lit.dev/docs/components/rendering/)
+ *
+ * This is not exactly a replacement, but it roughly follows the same idea.
+ *
+ * @example
+ * ```ts
+ * // Create a simple div
+ * h('div', { id: 'app' }, 'Hello World')
+ *
+ * // Create a nested structure
+ * h('ul', { class: 'list' },
+ *   h('li', null, 'Item 1'),
+ *   h('li', null, 'Item 2')
+ * )
+ * ```
+ *
+ * @param tagName - The HTML tag name.
+ * @param attributes - Attributes to set on the element. Can be null or undefined.
+ * @param children - Children to append (strings, nodes, or other JJHE instances).
+ * @returns The created JJHE instance.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement | document.createElement}
+ */
+declare function h(tagName: string, attributes?: Record<string, string> | null, ...children: Wrappable[]): JJHE;
+/**
+ * Creates a `<link>` element for prefetching or preloading resources.
+ *
+ * @remarks
+ * This function validates the input arguments and returns a wrapped `JJHE` instance.
+ * It does not append the element to the document.
+ *
+ * @param href - The URL of the resource.
+ * @param rel - The relationship of the linked resource ('prefetch' or 'preload').
+ * @param as - The type of content being loaded ('fetch' for HTML, 'style' for CSS, or 'script' for JavaScript files).
+ * If it's not provided or set to a falsy value, it runs heuristics to find the best match from the href parameter.
+ *
+ * @returns The JJHE instance representing the link element. The `<link>` is accessible via `.ref`
+ * @throws {TypeError} If `href` is not a string or URL.
+ * @throws {RangeError} If `rel` or `as` are not valid values.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload | Link types: preload}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch | Link types: prefetch}
+ */
+declare function createLinkPre(href: string | URL, rel: 'prefetch' | 'preload', as?: 'fetch' | 'style' | 'script'): JJHE;
+/**
+ * Adds a `<link>` tag to the document head for prefetching or preloading resources.
+ *
+ * @remarks
+ * This function helps in optimizing performance by telling the browser to fetch resources
+ * that might be needed later (prefetch) or are needed immediately (preload).
+ *
+ * Please refer to {@link createLinkPre} for more details.
+ *
+ * @example
+ * ```ts
+ * // Preload a script
+ * addLinkPre('https://example.com/script.js', 'preload', 'script')
+ *
+ * // Prefetch a future page's CSS
+ * addLinkPre('/next-page.css', 'prefetch', 'style')
+ * ```
+ *
+ * @param args - The arguments to be passed to {@link createLinkPre}.
+ * @returns The JJHE instance representing the link element.
+ * @throws {TypeError} If `href` is not a string or URL.
+ * @throws {RangeError} If `rel` or `as` are not valid values.
+ * @see {@link createLinkPre}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload | Link types: preload}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch | Link types: prefetch}
+ */
+declare function addLinkPre(...args: Parameters<typeof createLinkPre>): JJHE<HTMLElement>;
+/**
+ * Fetches a file and returns its contents as string.
+ *
+ * @remarks
+ * This is a wrapper around the native `fetch` API that handles the response status check
+ * and text extraction. It sets the `Accept` header based on the provided mime type.
+ *
+ * @example
+ * ```ts
+ * const text = await fetchText('https://example.com/data.txt')
+ * ```
+ *
+ * @param url - The file location.
+ * @param mime - The HTTP Request Accept header. Defaults to 'text/*'.
+ * @returns The file contents as a string.
+ * @throws {TypeError} If `mime` is not a string.
+ * @throws {Error} If the fetch fails or the response status is not OK (200-299).
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Response/text | Response.text()}
+ */
+declare function fetchText(url: URL | string, mime?: string): Promise<string>;
+/**
+ * Fetches the contents of a HTML file as string.
+ *
+ * @remarks
+ * Useful for loading HTML templates dynamically.
+ * You can use `import.meta.resolve('./relative-path-to.html')` to resolve paths relative to the current module.
+ *
+ * @example
+ * ```ts
+ * const template = await fetchHtml('./template.html')
+ * ```
+ *
+ * @param url - The HTML file location.
+ * @returns The file content as a string.
+ * @throws {Error} If the response is not ok.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types | MIME types}
+ */
+declare function fetchHtml(url: URL | string): Promise<string>;
+/**
+ * Fetches the contents of a CSS file as string.
+ *
+ * @remarks
+ * You can use `import.meta.resolve('./relative-path-to.css')` inside components to resolve relative paths.
+ *
+ * @example
+ * ```ts
+ * const css = await fetchCss('./style.css')
+ * ```
+ *
+ * @param url - The CSS file location.
+ * @returns The file content as a string.
+ * @throws {Error} If the response is not ok.
+ */
+declare function fetchCss(url: URL | string): Promise<string>;
+/**
+ * Fetches a CSS file and constructs a CSSStyleSheet.
+ *
+ * @remarks
+ * This is particularly useful for Constructable Stylesheets, which can be shared across Shadow DOM boundaries.
+ *
+ * @example
+ * ```ts
+ * const sheet = await fetchStyle('./component.css')
+ * shadowRoot.adoptedStyleSheets = [sheet]
+ * ```
+ *
+ * @param url - The CSS file location.
+ * @returns The CSSStyleSheet object constructed from the CSS contents.
+ * @throws {Error} If the fetch fails.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet | CSSStyleSheet}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets | adoptedStyleSheets}
+ */
+declare function fetchStyle(url: URL | string): Promise<CSSStyleSheet>;
+
+/**
+ * A helper to bridge the attribute world (kebab-case) to the property world (camelCase).
+ * It works in tandem with browser's `observedAttributes` feature which triggers
+ * `attributeChangedCallback`.
+ *
+ * @remarks
+ * Your custom component class MUST define `static observedAttributes[]` otherwise `attributeChangedCallback` won't trigger.
+ * `observedAttributes` should contain kebab-based attribute names.
+ *
+ * @example
+ * ```ts
+ * class MyComponent extends HTMLElement {
+ *     static observedAttributes = ['user-name', 'counter']
+ *     userName = '' // Property MUST exist on the instance (or prototype setter)
+ *     #counter = 0  // You can also use private properties together with getter/setters
+ *
+ *     attributeChangedCallback(name, oldValue, newValue) {
+ *         attr2prop(this, name, oldValue, newValue)
+ *     }
+
+ *     get counter() {
+ *         return this.#counter
+ *     }
+ *
+ *     set counter(value) {
+ *         this.#counter = value
+ *         this.#render() // You can call your render function to update the DOM
+ *     }
+ *
+ *     #render() {
+ *         const shadow = JJHE.from(this).shadow
+ *         if (shadow) {
+ *             shadow.find('#user').setText(this.userName)
+            shadow.find('#counter').setText(this.counter)
+ *         }
+ *     }
+ * }
+ * ```
+ *
+ * @param instance - A reference to the common component instance
+ * @param name - kebab-case and in lower case exactly as it appears in `observedAttributes`.
+ * @param oldValue - The previous value of the attribute.
+ * @param newValue - The new value of the attribute.
+ * @returns `true` if it tried to set the attribute; otherwise `false`.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes | Responding to attribute changes}
+ */
+declare function attr2prop(instance: HTMLElement, name: string, oldValue: any, newValue: any): boolean;
+/**
+ * Registers the custom element with the browser and waits till it is defined.
+ *
+ * @example
+ * ```ts
+ * class MyComponent extends HTMLElement {}
+ * await registerComponent('my-component', MyComponent)
+ * ```
+ * Another convention is to have a `static async register()` function in the Custom Component.
+ * ```ts
+ * export class MyComponent extends HTMLElement {
+ *     static async register() {
+ *         return registerComponent('my-component', MyComponent)
+ *     }
+ * }
+ * ```
+ * That way, you can import multiple components and do a `Promise.all()` on all their `.register()`s.
+ * ```ts
+ * import { MyComponent, YourComponent, TheirComponent } ...
+ * await Promise.all([
+ *     MyComponent.register(),
+ *     YourComponent.register(),
+ *     TheirComponent.register(),
+ * ])
+ *
+ * @throws {TypeError} If name is not a string or constructor is not a function
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define | customElements.define}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined | customElements.whenDefined}
+ */
+declare function registerComponent(name: string, constructor: CustomElementConstructor, options?: ElementDefinitionOptions): Promise<void>;
+
+/**
+ * Manages the resolution of Shadow DOM configuration (template and styles).
+ *
+ * Allows building up the configuration and resolving it lazily.
+ *
+ * @example
+ * ```ts
+ * const sm = ShadowMaster.create()
+ *   .setTemplate('<div>Hello World</div>')
+ *   .addStyles('div { color: red; }')
+ *
+ * class MyComponent extends HTMLElement {
+ *   async connectedCallback() {
+ *      // Resolves the config once and caches it
+ *      const shadowConfig = await sm.getResolved()
+ *      // ... init shadow root with shadowConfig
+ *   }
+ * }
+ * ```
+ */
+declare class ShadowMaster {
+    #private;
+    /**
+     * Creates a new instance of ShadowMaster.
+     *
+     * @returns A new ShadowMaster instance.
+     */
+    static create(): ShadowMaster;
+    constructor();
+    /**
+     * Sets the template configuration.
+     *
+     * @param templateConfig - The template configuration.
+     * @returns The instance for chaining.
+     *
+     * @example
+     * ```ts
+     * // Accepts string, promise, or fetchHtml result
+     * sm.setTemplate(fetchHtml('./template.html'))
+     * ```
+     */
+    setTemplate(templateConfig?: JJTemplateConfig): this;
+    /**
+     * Adds one or more style configurations.
+     *
+     * @param stylesConfig - Variable number of style configurations.
+     * @returns The instance for chaining.
+     *
+     * @example
+     * ```ts
+     * sm.addStyles(
+     *     'p { color: red; }',
+     *     fetchCss('./styles.css'),
+     *     () => fetchCss('../lazy-loaded-styles.css'),
+     * )
+     * ```
+     */
+    addStyles(...stylesConfig: JJStyleConfig[]): this;
+    /**
+     * Resolves the configuration to something that can be fed to `JJHE.initShadow()` function
+     *
+     * The result is cached, so subsequent calls return the same promise.
+     * Note: Any changes made to the ShadowMaster instance (via setTemplate/addStyles)
+     * after the first call to getResolved() will be ignored.
+     *
+     * @returns A promise resolving to the ShadowConfig.
+     */
+    getResolved(): Promise<ShadowConfig>;
+}
+
+/**
+ * A wrapped document for convenience.
+ * It can be used instead of document
+ *
+ * @example
+ * ```ts
+ * import { doc } from 'jj'
+ * const el = doc.find('#my-element') // A JJHE instance
+ * const body = doc.body             // A JJHE instance
+ * doc.addChild(JJHE.create('script').setAttr('src', 'my-code.js'))
+ * doc.head.addChild(JJHE.create('link').setAttr({
+ *   rel: 'stylesheet',
+ *   href: 'code.css'
+ * }))
+ * ```
+ */
+declare const doc: JJD<Document>;
+
+export { JJD, JJDF, JJE, JJET, JJHE, JJN, JJSE, JJSR, type JJStyleConfig, JJT, type JJTemplateConfig, type ShadowConfig, ShadowMaster, type Unwrapped, type Wrappable, type Wrapped, addLinkPre, attr2prop, createLinkPre, cssToStyle, doc, fetchCss, fetchHtml, fetchStyle, fetchText, fileExt, h, keb2cam, keb2pas, nextAnimationFrame, pas2keb, registerComponent, sleep };