@carlsebastian/jsu 1.0.34

package/src/utils/dom/element/create/element.create.js

@@ -0,0 +1,312 @@
+import Emit from '../../../custom/error/builder/error.builder.js';
+import { IsArrEmpty, IsPlainObjEmpty, IsStrEmpty } from '../../../guards/formats/formats.js';
+import { IsArr, IsElement, IsNum, IsPlainObj, IsStr } from '../../../guards/data-types/data-types.js';
+import { CountOf } from '../../../primitives/obj/obj.accessor.js';
+import ClassOf from '../../attr/attr.class.js';
+import IdOf from '../../attr/attr.id.js';
+import StyleOf from '../../attr/attr.style.js';
+import VerifyTag from '../tag-verifier/verifier.js';
+
+/* -- Helpers -- */
+/**
+ *  Handles the parameter validation of tag and configuration for element creation.
+ *
+ *  @param { string } caller - The caller id of this validation.
+ *  @param { string } tag - The tag to validate.
+ *  @param { Record<string, unknown> } conf - The configuration to validate.
+ *  @returns { void } Does not return any as it only handles the validation process.
+ */
+function ValidateTagAndConfiguration(caller, tag, conf) {
+    const Caller = IsStr(caller) ? caller : "(Anonymous)";
+
+    if (!IsStr(tag))
+        Emit._ArgumentError(Caller, "tag", tag, "String");
+
+    if (!IsPlainObj(conf))
+        Emit._ArgumentError(Caller, "conf", conf, "Plain Object ({})");
+}
+
+/**
+ *  Formats the configuration of element's properties.
+ *
+ *  @template T
+ *  @param { T } conf - the configuration to format.
+ *  @param { Array<string> } definedKeys - The default or expected property id of the configuration.
+ *  @returns { T extends Record<string, infer V> ? Record<string, V> : {} }
+ */
+function FormatConfig(conf, definedKeys) {
+    if (!IsPlainObj(conf))
+        return {};
+
+    if (!IsArr(definedKeys) || IsArrEmpty(definedKeys))
+        return conf;
+
+    if (IsPlainObjEmpty(conf))
+        return conf;
+
+    const DKLower = definedKeys.map(K => String(K).trim().toLowerCase()), ConfKeys = Object.keys(conf);
+
+    return ConfKeys.reduce((Acc, Key) => {
+        const Pos = DKLower.indexOf(Key.trim().toLowerCase());
+        if (Pos >= 0)
+            Acc[definedKeys[Pos]] = conf[Key];
+        else {
+            if (!Object.hasOwn(Acc, "Others"))
+                Acc["Others"] = {};
+
+            Acc["Others"][Key] = conf[Key];
+        }
+
+        return Acc;
+    }, {});
+}
+
+/**
+ *  Contains methods for `DOM` creation objects.
+ */
+const Create = {
+    /**
+     *  The name of this object.
+     */
+    Name: "Create",
+
+    /**
+     *  Generates an instance of `HTMLElement` with the given qualified `tag`.
+     *
+     *  @template { HTMLElementTags["Key"] } T
+     *  @param { T } tag - The tag of element to generate.
+     *  @param { HTMLElementConfig } [conf] - A configuration properties of element.
+     *  @returns { T extends HTMLElementTags["Key"] ? HTMLElementTags["Map"][T] : null }
+     *
+     *  @throws {ArgumentError} - When parameters are invalid.
+     *  @throws {NoSuchElementTagError} - When the given element tag is not qualified.
+     */
+    HTMLElement(tag, conf = {}) {
+        const Method = `${this.Name}.HTMLElement`;
+        let [Tag, Conf] = [tag, conf];
+
+        ValidateTagAndConfiguration(Method, Tag, Conf);
+
+        const ThisElement = VerifyTag(Tag).HTMLElement();
+        if (!IsElement(ThisElement)) {
+            console.warn(`${Method}(): There's no such element tag of '${Tag}'! (Exited with null)`);
+            return null;
+        }
+
+        const ConfigKeys = ["ClassNames", "Id", "Text", "Styles"];
+        Conf = FormatConfig(Conf, ConfigKeys);
+        if (CountOf(Conf) > 0) {
+            if (Conf.ClassNames)
+                ClassOf(ThisElement).Set(Conf.ClassNames);
+
+            if (Conf.Id)
+                IdOf(ThisElement).Set(Conf.Id);
+
+            if (Conf.Text) {
+                if (!IsStr(Conf.Text))
+                    Conf.Text = String(Conf.Text);
+
+                ThisElement.textContent = Conf.Text;
+            }
+
+            if (Conf.Styles)
+                StyleOf(ThisElement).Set(Conf.Styles);
+
+            if (Conf?.Others && IsPlainObj(Conf.Others) && CountOf(Conf.Others) > 0) {
+                for (const [OK, OV] of Object.entries(Conf.Others))
+                    ThisElement.setAttribute(OK, OV);
+            }
+        }
+
+        return ThisElement;
+    },
+
+    /**
+     *  Generates an instance of `SVGElement` with the given qualified tag.
+     *
+     *  @template { SVGElementTags["Key"] } T
+     *  @param { T } tag - The tag of svg element to generate.
+     *  @param { SVGElementConfig } [conf] - A configuration properties of svg element.
+     *  @returns { T extends SVGElementTags["Key"] ? SVGElementTags["Map"][T] : null }
+     *
+     *  @throws {ArgumentError} - When parameters are invalid.
+     *  @throws {NoSuchElementTagError} - When the given svg tag is not qualified.
+     */
+    SVGElement(tag, conf = {}) {
+        const Method = `${this.Name}.SVGElement`;
+        let [Tag, Conf] = [tag, conf];
+
+        ValidateTagAndConfiguration(Method, Tag, Conf);
+
+        const ThisElement = VerifyTag(Tag).SVGElement();
+        if (!IsElement(ThisElement)) {
+            console.warn(`${Method}(): There's no such svg element tag of '${Tag}'! (Exited with null)`);
+            return null;
+        }
+
+        const ConfKeys = ["ClassNames", "Id", "Styles", "TabIndex", "XML_Language", "XML_Space"];
+        Conf = FormatConfig(Conf);
+        if (CountOf(Conf) > 0) {
+            if (Conf.ClassNames)
+                ClassOf(ThisElement).Set(Conf.ClassNames);
+
+            if (Conf.Id)
+                IdOf(ThisElement).Set(Conf.Id);
+
+            if (Conf.Styles)
+                StyleOf(ThisElement).Set(Conf.Styles);
+
+            if (Conf.TabIndex) {
+                if (!IsNum(Conf.Tabindex)) {
+                    const ParsedIndex = parseInt(Conf.TabIndex, 10);
+                    if (!IsNum(ParsedIndex))
+                        Emit._ArgumentError(Method, "conf.TabIndex", Conf.TabIndex, "Number");
+
+                    Conf.TabIndex = ParsedIndex;
+                }
+
+                ThisElement.setAttribute("tabindex", Conf.TabIndex);
+            }
+
+            if (Conf.XML_Language) {
+                if (!IsStr(Conf.XML_Language))
+                    Emit._ArgumentError(Method, "conf.XML_Language", Conf.XML_Language, "String");
+
+                if (!IsStrEmpty(Conf.XML_Language))
+                    ThisElement.setAttribute("xml:lang", Conf.XML_Language);
+            }
+
+            if (Conf.XML_Space) {
+                if (!IsStr(Conf.XML_Space))
+                    Emit._ArgumentError(Method, "conf.XML_Space", Conf.XML_Space, "String");
+
+                if (IsStrEmpty(Conf.XML_Space) || Conf.XML_Space !== "default" && Conf.XML_Space !== "preserve")
+                    Conf.XML_Space = "default";
+
+                ThisElement.setAttribute("xml:space", Conf.XML_Space);
+            }
+
+            if (Conf?.Others && IsPlainObj(Conf.Others) && CountOf(Conf.Others) > 0) {
+                for (const [OK, OV] of Object.entries(Conf.Others))
+                    ThisElement.setAttribute(OK, OV);
+            }
+        }
+
+        return ThisElement;
+    },
+
+    /**
+     *  Generates an instance of `MathMLElement` with the given qualified tag.
+     *
+     *  @template { MathMLElementTags["Key"] } T
+     *  @param { T } tag - The tag of math element to generate.
+     *  @param { MathElementConfig } [conf] - A configuration properties of math element.
+     *  @returns { T extends MathMLElementTags["Key"] ? MathMLElementTags["Map"][T] : null }
+     *
+     *  @throws {ArgumentError} - When parameters are invalid.
+     *  @throws {NoSuchElementTagError} - When the given math tag is not qualified.
+     */
+    MathElement(tag, conf = {}) {
+        const Method = `${this.Name}.MathElement`;
+        let [Tag, Conf] = [tag, conf];
+
+        ValidateTagAndConfiguration(Method, Tag, Conf);
+
+        const ThisElement = VerifyTag(Tag).MathElement();
+        if (!IsElement(ThisElement)) {
+            console.warn(`${Method}(): There's no such math element tag of '${Tag}'! (Exited with null)`);
+            return null;
+        }
+
+        const ConfKeys = ["Data", "Dir", "DisplayStyle", "Href", "Id", "MathBackground", "MathColor", "MathSize", "ScriptLevel"];
+        Conf = FormatConfig(Conf, ConfKeys);
+        if (CountOf(Conf) > 0) {
+            if (Conf.Data) {
+                if (!IsPlainObj(Conf.Data))
+                    Emit._ArgumentError(Method, "conf.Data", Conf.Data, "Plain Object ({})");
+
+                if (CountOf(Conf.Data) > 0)
+                    for (const [DK, DV] of Object.entries(Conf.Data)) {
+                        if (!IsStr(DV)) {
+                            console.warn(`${Method}(@conf: { ${DK}: ${DV} }): Expects a string format value! (Skipped)`);
+                            continue;
+                        }
+
+                        if (IsStrEmpty(DV))
+                            continue;
+
+                        ThisElement.setAttribute(`data-${DK.trim().toLowerCase()}`, DV);
+                    }
+            }
+
+            if (Conf.Dir) {
+                if (!IsStr(Conf.Dir))
+                    Emit._ArgumentError(Method, "conf.Dir", Conf.Dir, "String");
+
+                if (IsStrEmpty(Conf.Dir) || (Conf.Dir !== "ltr" && Conf.Dir !== "rtl"))
+                    Conf.Dir = "ltr";
+
+                ThisElement.setAttribute("dir", Conf.Dir);
+            }
+
+            if (Conf.DisplayStyle && typeof Conf.DisplayStyle === "boolean")
+                ThisElement.setAttribute("displaystyle", Conf.DisplayStyle);
+
+            if (Conf.Href) {
+                if (!IsStr(Conf.Href))
+                    Emit._ArgumentError(Method, "conf.Href", Conf.Href, "String");
+
+                if (!IsStrEmpty(Conf.Href))
+                    ThisElement.setAttribute("href", Conf.Href);
+            }
+
+            if (Conf.Id) {
+                if (!IsStr(Conf.Id))
+                    Emit._ArgumentError(Method, "conf.Id", Conf.Id, "String");
+
+                if (!IsStrEmpty(Conf.Id))
+                    ThisElement.id = Conf.Id;
+            }
+
+            if (Conf.ScriptLevel) {
+                if (!IsStr(Conf.ScriptLevel))
+                    Emit._ArgumentError(Method, "conf.ScriptLevel", Conf.ScriptLevel, "String");
+
+                if (!IsStrEmpty(Conf.ScriptLevel))
+                    ThisElement.setAttribute("scriptlevel", Conf.ScriptLevel);
+            }
+
+            if (Conf.MathBackground) {
+                if (!IsStr(Conf.MathBackground))
+                    Emit._ArgumentError(Method, "conf.MathBackground", Conf.MathBackground, "String");
+
+                if (!IsStrEmpty(Conf.MathBackground))
+                    ThisElement.setAttribute("mathbackground", Conf.MathBackground);
+            }
+
+            if (Conf.MathColor) {
+                if (!IsStr(Conf.MathColor))
+                    Emit._ArgumentError(Method, "conf.MathColor", Conf.MathColor, "String");
+
+                if (!IsStrEmpty(Conf.MathColor))
+                    ThisElement.setAttribute("mathcolor", Conf.MathColor);
+            }
+
+            if (Conf.MathSize) {
+                if (!IsStr(Conf.MathSize))
+                    Emit._ArgumentError(Method, "conf.MathSize", Conf.MathSize, "String");
+
+                if (!IsStrEmpty(Conf.MathSize))
+                    ThisElement.setAttribute("mathsize", Conf.MathSize);
+            }
+
+            if (Conf?.Others && IsPlainObj(Conf.Others) && CountOf(Conf.Others) > 0) {
+                for (const [OK, OV] of Object.entries(Conf.Others))
+                    ThisElement.setAttribute(OK, OV);
+            }
+        }
+
+        return ThisElement;
+    }
+};
+export default Create;

package/src/utils/dom/element/getElementBy/dom.getElementBy.js

@@ -0,0 +1,171 @@
+import Emit from '../../../custom/error/builder/error.builder.js';
+import { IsNullOrUndefined, IsParentNode, IsStr } from '../../../guards/data-types/data-types.js';
+import { IsStrEmpty } from '../../../guards/formats/formats.js';
+import { XMLNameSpace } from '../../../variables.js';
+
+/**
+ *  Contains `DOMElement` retrieval methods.
+ */
+const GetElementBy = {
+    /**
+     *  The name of this object.
+     */
+    name: "GetElementBy",
+
+    /**
+     *  Search and retrieves the element that matches the given unique `id`.
+     *
+     *  @overload
+     *  @param { string } id - The unique `id` of element to search.
+     *  @returns { HTMLElement | "<NO_SUCH_ELEMENT_ID>" | null }
+     */
+    /**
+     *  Search and retrieve the element that matches the given unique `id`.
+     *
+     *  @overload
+     *  @param { string } id - The unique `id` of element to search.
+     *  @param { ParentNode } [root] - The parent element of where to search and retrieve element with the given unique `id`.  (Default: Document)
+     *  @returns { HTMLElement | "<NO_SUCH_ELEMENT_ID>" | null }
+     */
+    ID(id, root = document) {
+        const Method = `${this.name}.ID`;
+
+        if (!IsStr(id))
+            Emit._ArgumentError(Method, "id", id, "String");
+
+        if (IsStrEmpty(id)) {
+            console.warn(`${Method}(@id: \'\'): Expects a non-empty-string! (Exited with null)`);
+            return null;
+        }
+
+        if (typeof root.getElementById !== "function") {
+            console.warn(`${Method}(@root: NOT_SUPPORTED_ROOT): Expects a root element that supports 'getElementById'! (Exited with null)`);
+            return null;
+        }
+
+        return root.getElementById(id) ?? "<NO_SUCH_ELEMENT_ID>";
+    },
+
+    /**
+     *  Search and retrieves the elements that matches the given class name.
+     *
+     *  @overload
+     *  @param { string } cls - The class name of elements to search.
+     *  @returns { HTMLCollectionOf<Element> }
+     */
+    /**
+     *  Search and retrieves the elements that matches the given class name.
+     *
+     *  @overload
+     *  @param { string } cls - The class name of elements to search.
+     *  @param { ParentNode } [root] - The parent element of where to search and retrieve elements with the given class name.  (Default: Document)
+     *  @returns { HTMLCollectionOf<Element> }
+     */
+    ClassName(cls, root = document) {
+        const Method = `${this.name}.ClassName`;
+
+        if (!IsStr(cls))
+            Emit._ArgumentError(Method, "cls", cls, "String");
+
+        if (IsStrEmpty(cls)) {
+            console.warn(`${Method}(@cls: \'\'): Expects a non-empty-string! (Exited with [])`);
+            return [];
+        }
+
+        if (!IsParentNode(root)) {
+            console.warn(`${Method}(@root: NOT_SUPPORTED_ROOT): Expects a root element that supports 'getElementsByClassName'! (Exited with [])`);
+            return [];
+        }
+
+        return root.getElementsByClassName(cls);
+    },
+
+    /**
+     *  Search and retrieves the elements that matches the given tag name.
+     *
+     *  @template { keyof ElementTags } T
+     *  @overload
+     *  @param { T } tag - The tag of element to retrieve.
+     *  @returns { HTMLCollectionOf<ResolveTag<T>> }
+     */
+    /**
+     *  Search and retrieves the elements that matches the given tag name.
+     *
+     *  @template { keyof ElementTags } T
+     *  @overload
+     *  @param { T } tag - The tag of element to retrieve.
+     *  @param { ParentNode } [root] - The parent element of where to search and retrieve the elements that matches the given tag.  (Default: Document)
+     *  @returns { HTMLCollectionOf<ResolveTag<T>> }
+     */
+    TagName(tag, root = document) {
+        const Method = `${this.name}.TagName`;
+
+        if (!IsStr(tag))
+            Emit._ArgumentError(Method, "tag", tag, "String");
+
+        if (IsStrEmpty(tag)) {
+            console.warn(`${Method}(@tag: \'\'): Expects a non-empty-string! (Exited with [])`);
+            return [];
+        }
+
+        if (!IsParentNode(root)) {
+            console.warn(`${Method}(@root: NOT_SUPPORTED_ROOT): Expects a root element that supports 'getElementsByTagName'! (Exited with [])`)
+            return [];
+        }
+
+        return root.getElementsByTagName(tag);
+    },
+
+    /**
+     *  Search and retrieves the elements that matches the given namespace and tag name.
+     *
+     *  @template { keyof ElementTags } T
+     *  @template { XMLNameSpace } NS
+     *  @overload
+     *  @param { NS } namespace - The namespace of element to retrieve.
+     *  @param { T } tag - The tag of element with the given namespace to retrieve.
+     *  @returns { HTMLCollectionOf<ResolveTagNS<NS, T>> }
+     */
+    /**
+     *  Search and retrieves the elements that matches the given namespace and tag name.
+     *
+     *  @template { keyof ElementTags } T
+     *  @template { XMLNameSpace } NS
+     *  @overload
+     *  @param { NS } namespace - The namespace of element to retrieve.
+     *  @param { T } tag - The tag of element with the given namespace to retrieve.
+     *  @param { ParentNode } [root] - The parent element of where to search and retrieve the elements with the given namespace and tag. (Default: Document)
+     *  @returns { HTMLCollectionOf<ResolveTagNS<NS, T>> }
+     */
+    TagNameNS(namespace, tag, root = document) {
+        const Method = `${this.name}.TagNameNS`;
+
+        if (!IsStr(namespace))
+            Emit._ArgumentError(Method, "namespace", namespace, "String");
+
+        if (!IsStr(tag))
+            Emit._ArgumentError(Method, "tag", tag, "String");
+
+        if (IsStrEmpty(namespace)) {
+            console.warn(`${Method}(@namespace: \'\'): Expects a non-empty-string! (Exited with [])`);
+            return [];
+        }
+
+        if (IsStrEmpty(tag)) {
+            console.warn(`${Method}(@tag: \'\'): Expects a non-empty-string! (Exited with [])`);
+            return [];
+        }
+
+        if (!XMLNameSpace.includes(namespace))
+            console.warn(`${Method}(@namespace: ${namespace}): Received a unknown XML namespace of element! It will be treated as custom element but it might cause to throw an error when it violates the format.`);
+
+        if (!IsParentNode(root)) {
+            console.warn(`${Method}(@root: NOT_SUPPORTED_ROOT): Expects a root element that supports 'getElementsByTagNameNS'! (Exited with [])`);
+            return [];
+        }
+
+        return root.getElementsByTagNameNS(namespace, tag);
+    }
+}
+
+export default GetElementBy;

package/src/utils/dom/element/query/dom.query.js

@@ -0,0 +1,75 @@
+import Emit from '../../../custom/error/builder/error.builder.js';
+import { IsStr, IsParentNode } from '../../../guards/data-types/data-types.js';
+import { IsStrEmpty } from '../../../guards/formats/formats.js';
+
+/**
+ *  Search and retrieves the first `DOMElement` that matches the given selector.
+ *
+ *  @template { keyof ElementTags } T
+ *  @overload
+ *  @param { T } selector - The selector of element to search.
+ *  @returns { ResolveTag<T> } The first element that matches the given selector.
+ */
+/**
+ *  Search and retrieves the first `DOMElement` that matches the given selector.
+ *
+ *  @template { keyof ElementTags } T
+ *  @overload
+ *  @param { T } selector - The selector of element to search.
+ *  @param { ParentNode } [root] - The parent node of where to look the given selector at. (Default: Document)
+ *  @returns { ResolveTag<T> } The first element that matches the given selector.
+ */
+export function Select(selector, root = document) {
+    const Method = "Select";
+
+    if (!IsStr(selector))
+        Emit._ArgumentError(Method, "selector", selector, "String");
+
+    if (IsStrEmpty(selector)) {
+        console.warn(`${Method}(@selector: \'\'): Expects a non-empty-string! (Exited with null)`);
+        return null;
+    }
+
+    if (!IsParentNode(root)) {
+        console.warn(`${Method}(@root: ${root}): Expects a root element that supports 'querySelector'! (Exited with null)`);
+        return null;
+    }
+
+    return root.querySelector(selector);
+}
+
+/**
+ *  Search and retrieves a collection of elements that matches the given selector.
+ *
+ *  @template { keyof ElementTags } T
+ *  @overload
+ *  @param { T } selector - The selector of elements to search.
+ *  @returns { ResolveTag<T>[] } The collection of elements that matches the given selector.
+ */
+/**
+ *  Search and retrieves a collection of elements that matches the given selector.
+ *
+ *  @template { keyof ElementTags } T
+ *  @overload
+ *  @param { T } selector - The selector of elements to search.
+ *  @param { ParentNode } [root] - The parent node of where to look the given selector at. (Default: Document)
+ *  @returns { ResolveTag<T>[] } The collection of elements that matches the given selector.
+ */
+export function SelectAll(selector, root = document) {
+    const Method = "SelectAll";
+
+    if (!IsStr(selector))
+        Emit._ArgumentError(Method, "selector", selector, "String");
+
+    if (IsStrEmpty(selector)) {
+        console.warn(`${Method}(@selector: \'\'): Expects a non-empty-string! (Exited with null)`);
+        return null;
+    }
+
+    if (!IsParentNode(root)) {
+        console.warn(`${Method}(@root: ${root}): Expects a root element that supports 'querySelectorAll'! (Exited with null)`);
+        return null;
+    }
+
+    return Array.from(root.querySelectorAll(selector));
+}

package/src/utils/dom/element/tag-verifier/verifier.js

@@ -0,0 +1,60 @@
+import Emit from '../../../custom/error/builder/error.builder.js';
+import { IsStrEmpty } from '../../../guards/formats/formats.js';
+import { IsStr } from '../../../guards/data-types/data-types.js';
+import * as VAR from '../../../variables.js';
+
+/**
+ *  Verifies the specified tag of `Element` and returns its representative `Element`.
+ *
+ *  @template { keyof ElementTags } KTag
+ *  @param { KTag } tag - The tag of Element to verify.
+ *  @returns The response object methods for element instance verification type.
+ */
+export default function VerifyTag(tag) {
+    const Method = "VerifyTag";
+
+    if (!IsStr(tag) || IsStrEmpty(tag))
+        Emit._ArgumentError(Method, "tag", tag, "String");
+
+    tag = tag.trim().toLowerCase()
+    return {
+        /**
+         *  Verifies the provided tag from the collection of `HTMLElementTagsMap` and returns a generated
+         *  `HTMLElement` instance from it, if its qualified.
+         *
+         *  @returns { VerifierTagAPI<KTag> }
+         */
+        HTMLElement() {
+            if (!VAR.HTMLElementTags.has(tag))
+                Emit._NoSuchElementTagError(`${Method}.HTMLElement`, "tag", tag, "HTMLElement");
+
+            return VAR.HTMLElementTags.get(tag)?.Generate() ?? null;
+        },
+
+        /**
+         *  Verifies the provided tag from the collection of `SVGElementTagsMap` and returns generated
+         *  `SVGElement` instance from it, if its qualified.
+         *
+         *  @returns { VerifierTagAPI<K> }
+         */
+        SVGElement() {
+            if (!VAR.SVGElementTags.has(tag))
+                Emit._NoSuchElementTagError(`${Method}.SVGElement`, "tag", tag, "SVGElement");
+
+            return VAR.SVGElementTags.get(tag)?.Generate() ?? null;
+        },
+
+        /**
+         *  Verifies the provided tag from the collection of `MathMLElementTagsMap` and returns generated
+         *  `MathMlElement` instance from it, if its qualified.
+         *
+         *  @returns { VerifierTagAPI<K> }
+         */
+        MathElement() {
+            if (!VAR.MathMLElementTags.has(tag))
+                Emit._NoSuchElementTagError(`${Method}.MathMLElement`, "tag", tag, "MathMLElement");
+
+            return VAR.MathMLElementTags.get(tag)?.Generate();
+        }
+    }
+}

package/src/utils/dom/lifecycle/mount.js

@@ -0,0 +1,48 @@
+import Emit from '../../custom/error/builder/error.builder.js';
+import { IsChildNode, IsParentNode, IsPropertyAt } from '../../guards/data-types/data-types.js';
+
+/**
+ *  Mounts the given `childNode` to the specified `parentNode`.
+ *
+ *  ***Reference***:
+ *      `appendChild()`.
+ *
+ *  @overload
+ *  @param { ParentNode } parentNode - The parent node to mount the given `childNode` at.
+ *  @param { ChildNode } childNode - The `childNode` to mount at `parentNode`.
+ *  @returns { void }
+ */
+/**
+ *  Mounts the given `childNode` collection to the specified `parentNode`.
+ *
+ *  ***Reference***:
+ *      `appendChild()`
+ *
+ *  @overload
+ *  @param { ParentNode } parentNode - The parent node to mount the given `childNode` collection at.
+ *  @param { ...ChildNode } childNodes - The `childNode` collection to mount at `parentNode`.
+ *  @returns { void }
+ */
+export default function Mount(parentNode, ...childNodes) {
+    const Method = "Mount", PCN = childNodes.length > 1 ? "childNodes" : "childNode";
+
+    if (!IsParentNode(parentNode))
+        Emit._ArgumentError(Method, "parentNode", parentNode, "ParentNode");
+
+    if (childNodes.length === 0) {
+        console.warn(`${Method}(@childNode: NOT_PROVIDED): Expects at least 1 or more child node(s) to mount! (Exited)`);
+        return;
+    }
+
+    if (!IsPropertyAt(parentNode, "appendChild")) {
+        console.warn(`${Method}(@parentNode: NOT_SUPPORTED_METHOD): The specified parent node does not support the property method 'appendChild'! (Exited)`);
+        return;
+    }
+
+    for (const Node of childNodes) {
+        if (!IsChildNode(Node))
+            Emit._ArgumentError(Method, PCN, Node, "ChildNode");
+
+        parentNode.appendChild(Node);
+    }
+}