tiny-essentials 1.19.3 → 1.20.1

package/dist/v1/libs/TinyHtml.d.mts

@@ -277,15 +277,31 @@ declare class TinyHtml {
             y: number;
         };
     };
+    /**
+     * Creates a new TinyHtml element from a tag name and optional attributes.
+     *
+     * You can alias this method for convenience:
+     * ```js
+     * const createElement = TinyHtml.createFrom;
+     * const myDiv = createElement('div', { class: 'box' });
+     * ```
+     *
+     * @param {string} tagName - The HTML tag name (e.g., 'div', 'span', 'button').
+     * @param {Record<string, string|null>} [attrs] - Optional key-value pairs representing HTML attributes.
+     *                                                If the value is `null`, the attribute will still be set with an empty value.
+     * @returns {TinyHtml} - A new instance of TinyHtml representing the created element.
+     * @throws {TypeError} - If `tagName` is not a string, or `attrs` is not a plain object when defined.
+     */
+    static createFrom(tagName: string, attrs?: Record<string, string | null>): TinyHtml;
     /**
      * Creates a new DOM element with the specified tag name and options, then wraps it in a TinyHtml instance.
      *
      * @param {string} tagName - The tag name of the element to create (e.g., 'div', 'span').
-     * @param {ElementCreationOptions} ops - Optional settings for creating the element.
+     * @param {ElementCreationOptions} [ops] - Optional settings for creating the element.
      * @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM element.
      * @throws {TypeError} If tagName is not a string or ops is not an object.
      */
-    static createElement(tagName: string, ops: ElementCreationOptions): TinyHtml;
+    static createElement(tagName: string, ops?: ElementCreationOptions): TinyHtml;
     /**
      * Creates a new TinyHtml instance that wraps a DOM TextNode.
      *
@@ -319,9 +335,9 @@ declare class TinyHtml {
      *
      * @param {string} selector - A valid CSS selector string.
      * @param {Document|Element} elem - Target element.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the matched elements.
      */
-    static queryAll(selector: string, elem?: Document | Element): TinyHtml[];
+    static queryAll(selector: string, elem?: Document | Element): TinyHtml;
     /**
      * Retrieves an element by its ID and wraps it in a TinyHtml instance.
      *
@@ -334,16 +350,16 @@ declare class TinyHtml {
      *
      * @param {string} selector - The class name to search for.
      * @param {Document|Element} elem - Target element.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
-    static getByClassName(selector: string, elem?: Document | Element): TinyHtml[];
+    static getByClassName(selector: string, elem?: Document | Element): TinyHtml;
     /**
      * Retrieves all elements with the specified name attribute and wraps them in TinyHtml instances.
      *
      * @param {string} selector - The name attribute to search for.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
-    static getByName(selector: string): TinyHtml[];
+    static getByName(selector: string): TinyHtml;
     /**
      * Retrieves all elements with the specified local tag name within the given namespace URI,
      * and wraps them in TinyHtml instances.
@@ -351,25 +367,31 @@ declare class TinyHtml {
      * @param {string} localName - The local name (tag) of the elements to search for.
      * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
      * @param {Document|Element} elem - Target element.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
-    static getByTagNameNS(localName: string, namespaceURI?: string | null, elem?: Document | Element): TinyHtml[];
+    static getByTagNameNS(localName: string, namespaceURI?: string | null, elem?: Document | Element): TinyHtml;
     /**
-     * @param {TinyElement|EventTarget|null|(TinyElement|EventTarget|null)[]} elems
-     * @param {string} where
-     * @param {any[]} TheTinyElements
-     * @param {string[]} elemName
-     * @returns {any[]}
+     * Prepares and validates multiple elements against allowed types.
+     *
+     * @param {TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[]} elems - The input elements to validate.
+     * @param {string} where - The method name or context calling this.
+     * @param {any[]} TheTinyElements - The list of allowed constructors (e.g., Element, Document).
+     * @param {string[]} elemName - The list of expected element names for error reporting.
+     * @returns {any[]} - A flat array of validated elements.
+     * @throws {Error} - If any element is not an instance of one of the allowed types.
      * @readonly
      */
     static readonly _preElemsTemplate(elems: TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[], where: string, TheTinyElements: any[], elemName: string[]): any[];
     /**
-     * @param {TinyElement|EventTarget|null|(TinyElement|EventTarget|null)[]} elems
-     * @param {string} where
-     * @param {any[]} TheTinyElements
-     * @param {string[]} elemName
-     * @param {boolean} [canNull=false]
-     * @returns {any}
+     * Prepares and validates a single element against allowed types.
+     *
+     * @param {TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[]} elems - The input element or list to validate.
+     * @param {string} where - The method name or context calling this.
+     * @param {any[]} TheTinyElements - The list of allowed constructors (e.g., Element, Document).
+     * @param {string[]} elemName - The list of expected element names for error reporting.
+     * @param {boolean} [canNull=false] - Whether `null` is allowed as a valid value.
+     * @returns {any} - The validated element or `null` if allowed.
+     * @throws {Error} - If the element is not valid or if multiple elements are provided.
      * @readonly
      */
     static readonly _preElemTemplate(elems: TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[], where: string, TheTinyElements: any[], elemName: string[], canNull?: boolean): any;
@@ -941,9 +963,21 @@ declare class TinyHtml {
      * @type {Record<string | symbol, string>}
      */
     static "__#6@#cssPropAliases": Record<string | symbol, string>;
-    /** @type {Record<string | symbol, string>} */
+    /**
+     * Public proxy to manage camelCase ➝ kebab-case CSS property aliasing.
+     *
+     * Modifying this object ensures that the reverse mapping in `cssPropRevAliases` is updated accordingly.
+     *
+     * @type {Record<string | symbol, string>}
+     */
     static cssPropAliases: Record<string | symbol, string>;
-    /** @type {Record<string | symbol, string>} */
+    /**
+     * Reverse map of `cssPropAliases`, mapping kebab-case back to camelCase CSS property names.
+     *
+     * This enables consistent bidirectional lookups of style properties.
+     *
+     * @type {Record<string | symbol, string>}
+     */
     static cssPropRevAliases: Record<string | symbol, string>;
     /**
      * Converts a camelCase string to kebab-case
@@ -1629,13 +1663,52 @@ declare class TinyHtml {
      */
     static trigger(el: TinyEventTarget | TinyEventTarget[], event: string, payload?: Event | CustomEvent | CustomEventInit): TinyEventTarget | TinyEventTarget[];
     /**
-     * Property name normalization similar to jQuery's propFix.
-     * @readonly
+     * Internal property name normalization map (similar to jQuery's `propFix`).
+     * Maps attribute-like names to their JavaScript DOM property equivalents.
+     *
+     * Example: `'for'` ➝ `'htmlFor'`, `'class'` ➝ `'className'`.
+     *
+     * ⚠️ Do not modify this object directly. Use `TinyHtml.propFix` to ensure reverse mapping (`attrFix`) remains in sync.
+     *
+     * @type {Record<string | symbol, string>}
      */
-    static readonly _propFix: {
-        for: string;
-        class: string;
-    };
+    static "__#6@#propFix": Record<string | symbol, string>;
+    /**
+     * Public proxy for normalized DOM property names.
+     *
+     * Setting a new entry here will also automatically update the reverse map in `TinyHtml.attrFix`.
+     *
+     * @type {Record<string | symbol, string>}
+     */
+    static propFix: Record<string | symbol, string>;
+    /**
+     * Reverse map of `propFix`, mapping property names back to their attribute equivalents.
+     *
+     * Used when converting DOM property names into HTML attribute names.
+     *
+     * @type {Record<string | symbol, string>}
+     */
+    static attrFix: Record<string | symbol, string>;
+    /**
+     * Normalizes an attribute name to its corresponding DOM property name.
+     *
+     * Example: `'class'` ➝ `'className'`, `'for'` ➝ `'htmlFor'`.
+     * If the name is not mapped, it returns the original name.
+     *
+     * @param {string} name - The attribute name to normalize.
+     * @returns {string} - The corresponding property name.
+     */
+    static getPropName(name: string): string;
+    /**
+     * Converts a DOM property name back to its corresponding attribute name.
+     *
+     * Example: `'className'` ➝ `'class'`, `'htmlFor'` ➝ `'for'`.
+     * If the name is not mapped, it returns the original name.
+     *
+     * @param {string} name - The property name to convert.
+     * @returns {string} - The corresponding attribute name.
+     */
+    static getAttrName(name: string): string;
     /**
      * Get an attribute on an element.
      * @param {TinyElement} el
@@ -1833,9 +1906,9 @@ declare class TinyHtml {
     /**
      * Creates an instance of TinyHtml for a specific Element.
      * Useful when you want to operate repeatedly on the same element using instance methods.
-     * @param {ConstructorElValues} el - The element to wrap and manipulate.
+     * @param {ConstructorElValues|ConstructorElValues[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} el - The element to wrap and manipulate.
      */
-    constructor(el: ConstructorElValues);
+    constructor(el: ConstructorElValues | ConstructorElValues[] | NodeListOf<Element> | HTMLCollectionOf<Element> | NodeListOf<HTMLElement>);
     /**
      * Queries the element for the first element matching the CSS selector and wraps it in a TinyHtml instance.
      *
@@ -1847,39 +1920,69 @@ declare class TinyHtml {
      * Queries the element for all elements matching the CSS selector and wraps them in TinyHtml instances.
      *
      * @param {string} selector - A valid CSS selector string.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the matched elements.
      */
-    querySelectorAll(selector: string): TinyHtml[];
+    querySelectorAll(selector: string): TinyHtml;
     /**
      * Retrieves all elements with the specified class name and wraps them in TinyHtml instances.
      *
      * @param {string} selector - The class name to search for.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
-    getElementsByClassName(selector: string): TinyHtml[];
+    getElementsByClassName(selector: string): TinyHtml;
     /**
      * Retrieves all elements with the specified local tag name within the given namespace URI,
      * and wraps them in TinyHtml instances.
      *
      * @param {string} localName - The local name (tag) of the elements to search for.
      * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
-    getElementsByTagNameNS(localName: string, namespaceURI?: string | null): TinyHtml[];
+    getElementsByTagNameNS(localName: string, namespaceURI?: string | null): TinyHtml;
     /**
      * Returns the current target held by this instance.
      *
+     * @param {number} index - The index of the element to retrieve.
      * @returns {ConstructorElValues} - The instance's target element.
      */
-    get(): ConstructorElValues;
+    get(index: number): ConstructorElValues;
+    /**
+     * Extracts a single DOM element from the internal list at the specified index.
+     *
+     * @param {number} index - The index of the element to extract.
+     * @returns {TinyHtml} A new TinyHtml instance wrapping the extracted element.
+     */
+    extract(index: number): TinyHtml;
+    /**
+     * Checks whether the element exists at the given index.
+     *
+     * @param {number} index - The index to check.
+     * @returns {boolean} - True if the element exists; otherwise, false.
+     */
+    exists(index: number): boolean;
+    /**
+     * Returns the current targets held by this instance.
+     *
+     * @returns {ConstructorElValues[]} - The instance's targets element.
+     */
+    getAll(): ConstructorElValues[];
     /**
      * Returns the current Element held by this instance.
      *
      * @param {string} where - The method name or context calling this.
+     * @param {number} index - The index of the element to retrieve.
      * @returns {ConstructorElValues} - The instance's element.
      * @readonly
      */
-    readonly _getElement(where: string): ConstructorElValues;
+    readonly _getElement(where: string, index: number): ConstructorElValues;
+    /**
+     * Returns the current Elements held by this instance.
+     *
+     * @param {string} where - The method name or context calling this.
+     * @returns {ConstructorElValues[]} - The instance's elements.
+     * @readonly
+     */
+    readonly _getElements(where: string): ConstructorElValues[];
     /**
      * Returns only the elements **not** matching the given selector or function.
      *