@simplybuilder/core-dom 2.0.0

package/lib/main.esm.mjs

@@ -0,0 +1,594 @@
+/*! SBCoreDom version 2.0.0 */
+/**
+ * @module DomStoreModule
+ * @description
+ * Key-value store for DOM element references. Elements can be registered
+ * by a string key and retrieved or removed later. Supports two removal modes:
+ * mode 1 (with EventModule cleanup) and mode 2 (store only).
+ */
+const ElementRefStore = {};
+/**
+ * Registers a DOM element in the store under a unique key.
+ * If the key already exists, the operation is silently ignored.
+ *
+ * @function addElementToStore
+ * @param {Object} data - Registration data.
+ * @param {string} data.key - Unique identifier for the element.
+ * @param {Element} data.value - The DOM element to store.
+ */
+function addElementToStore(data) {
+    const { key, value } = data;
+    if (key && value) {
+        if (typeof ElementRefStore[key] === 'undefined') {
+            ElementRefStore[key] = value;
+        }
+    }
+}
+/**
+ * Retrieves a stored DOM element by its key.
+ *
+ * @function getElementFromStore
+ * @param {string} key - The element's unique key.
+ * @returns {Element|undefined} - The stored element, or undefined.
+ */
+function getElementFromStore(key) {
+    if (key)
+        return ElementRefStore[key];
+    return undefined;
+}
+/**
+ * Removes a DOM element from the store by its key.
+ * In mode 1 (default), calls `EventModule.removeAllEventsFromStore`
+ * before deleting. In mode 2, deletes from store only.
+ *
+ * @function removeElementFromStore
+ * @param {Object} data - Removal data.
+ * @param {string} data.key - The element's unique key.
+ * @param {number} [data.mode=1] - Removal mode: 1 with event cleanup, 2 store only.
+ * @param {Object} [data.EventModule] - Optional EventModule for listener cleanup.
+ * @returns {boolean} - True if the element was found and removed.
+ */
+function removeElementFromStore(data) {
+    const { key, mode = 1, EventModule = {} } = data;
+    if (!key)
+        return false;
+    try {
+        const element = ElementRefStore[key];
+        if (!element)
+            return false;
+        if (mode === 1 && typeof EventModule.removeAllEventsFromStore === 'function') {
+            EventModule.removeAllEventsFromStore(element);
+        }
+        delete ElementRefStore[key];
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Removes all entries from the store. Used for testing.
+ *
+ * @function clearStore
+ */
+function clearStore() {
+    for (const key of Object.keys(ElementRefStore)) {
+        delete ElementRefStore[key];
+    }
+}/**
+ * @module DomExtensionModule
+ * @description
+ * Extension system for the DOM module. Allows external modules (e.g., EventModule)
+ * to register themselves via `domModuleExtends()` and hook into the DOM creation
+ * and removal pipeline. Version validation ensures compatibility at runtime.
+ */
+/**
+ * Internal store for module metadata, registered extensions, and version constraints.
+ *
+ * @private
+ * @ignore
+ * @type {Object}
+ */
+const internalStore = {
+    app: {
+        name: 'DomModule',
+        version: "2.0.0",
+    },
+    register: {},
+    allow: {
+        SBCoreEvent: { major: 2 },
+    },
+    clearExtensions() {
+        for (const key of Object.keys(this.register)) {
+            delete this.register[key];
+        }
+    },
+};
+/**
+ * Validates that a module's version meets the minimum version requirements
+ * defined in `internalStore.allow`. Checks major, minor, and patch levels.
+ *
+ * @function validVersionSupport
+ * @param {Object} data - Module data with name and version.
+ * @param {string} data.name - Module identifier (e.g., 'EventModule').
+ * @param {string} data.version - Semantic version string (e.g., '1.0.0').
+ * @returns {boolean} - True if the module version is supported.
+ */
+function validVersionSupport(data) {
+    const { name, version } = data;
+    const constraint = internalStore.allow[name];
+    if (constraint && version) {
+        const arrVersion = version.split('.');
+        if (arrVersion.length >= 1) {
+            if (constraint.major !== undefined && arrVersion[0] && constraint.major > Number(arrVersion[0]))
+                return false;
+            if (constraint.minor !== undefined && arrVersion[1] && constraint.minor > Number(arrVersion[1]))
+                return false;
+            if (constraint.patch !== undefined && arrVersion[2] && constraint.patch > Number(arrVersion[2]))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Registers an external module for DOM module integration.
+ * Validates version compatibility before storing.
+ * The registered module is then available to `createEventElement` and
+ * `removeElement` for declarative event binding and cleanup.
+ *
+ * @function domModuleExtends
+ * @param {Object} data - Module data.
+ * @param {string} data.name - Module identifier stored as key.
+ * @param {string} data.version - Module version for compatibility check.
+ * @returns {boolean} - True if registration was successful.
+ */
+function domModuleExtends(data) {
+    try {
+        const { name } = data;
+        if (validVersionSupport(data)) {
+            internalStore.register[name] = data;
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+/**
+ * Returns the first registered extension, regardless of name.
+ * Used by struct.ts to find the EventModule without knowing its name.
+ *
+ * @function getAnyExtension
+ * @returns {Object|undefined} - The first registered module, or undefined.
+ */
+function getAnyExtension() {
+    for (const key of Object.keys(internalStore.register)) {
+        return internalStore.register[key];
+    }
+    return undefined;
+}/**
+ * @module DomAttributeModule
+ * @description
+ * Utility functions for setting standard and namespaced attributes on DOM elements.
+ */
+/**
+ * Sets standard attributes on a DOM element.
+ * Iterates the attributes array and calls `element.setAttribute` for each entry.
+ *
+ * @function setAttr
+ * @param {Object} data - Attribute data.
+ * @param {HTMLElement|SVGElement} data.element - The target element.
+ * @param {Array<{name: string, value: string}>} data.attrs - Array of attribute name/value pairs.
+ */
+function setAttr(data) {
+    const { element, attrs } = data;
+    if (!attrs || attrs.length === 0)
+        return;
+    for (let i = attrs.length - 1; i >= 0; i--) {
+        const item = attrs[i];
+        if (item?.name) {
+            element.setAttribute(item.name, item.value);
+        }
+    }
+}
+/**
+ * Sets namespaced attributes on a DOM element (e.g., SVG attributes).
+ * Calls `element.setAttributeNS(null, name, value)` for each entry.
+ *
+ * @function setAttrNS
+ * @param {Object} data - Namespaced attribute data.
+ * @param {HTMLElement|SVGElement} data.element - The target element.
+ * @param {Array<{name: string, value: string}>} data.attrs - Array of attribute name/value pairs.
+ */
+function setAttrNS(data) {
+    const { element, attrs } = data;
+    if (!attrs || attrs.length === 0)
+        return;
+    for (let i = attrs.length - 1; i >= 0; i--) {
+        const item = attrs[i];
+        if (item?.name) {
+            element.setAttributeNS(null, item.name, item.value);
+        }
+    }
+}/**
+ * @module DomDatasetModule
+ * @description
+ * Utility for setting dataset properties on DOM elements.
+ * When the dataset name is `state`, the element is automatically
+ * registered in the element store for later retrieval.
+ */
+/**
+ * Sets dataset properties on a DOM element.
+ * If a dataset entry has `name === 'state'`, the element is also
+ * registered in the element store using the state value as key.
+ *
+ * @function setData
+ * @param {Object} data - Dataset data.
+ * @param {HTMLElement|SVGElement} data.element - The target element.
+ * @param {Array<{name: string, value: string}>} data.dataset - Array of dataset name/value pairs.
+ */
+function setData(data) {
+    const { element, dataset } = data;
+    if (!dataset || dataset.length === 0)
+        return;
+    for (let i = dataset.length - 1; i >= 0; i--) {
+        const item = dataset[i];
+        if (item?.name) {
+            element.dataset[item.name] = item.value;
+            if (item.name === 'state') {
+                addElementToStore({ key: item.value, value: element });
+            }
+        }
+    }
+}/**
+ * @module DomComponentModule
+ * @description
+ * Provides functions for creating and appending HTML and SVG elements.
+ * Handles attribute assignment, dataset configuration, and shadow DOM creation.
+ */
+/**
+ * Attaches a shadow root to an HTML element with the specified mode.
+ *
+ * @private
+ * @ignore
+ * @function attachShadow
+ * @param {HTMLElement} host - The element to attach the shadow root to.
+ * @param {'open'|'closed'} mode - The shadow DOM mode.
+ * @returns {ShadowRoot} The created shadow root.
+ */
+function attachShadow(host, mode) {
+    return host.attachShadow({ mode });
+}
+/**
+ * Creates a shadow root from a string or object configuration.
+ * String mode creates a shadow root with that mode ('open'/'closed').
+ * Object mode can additionally include `styles` via CSSStyleSheet.
+ *
+ * @private
+ * @ignore
+ * @function createShadowFromConfig
+ * @param {HTMLElement} host - The element to attach the shadow root to.
+ * @param {ShadowConfig} shadow - Shadow configuration (string or object with mode/styles).
+ * @returns {ShadowRoot|undefined} The created shadow root, or undefined on failure.
+ */
+function createShadowFromConfig(host, shadow) {
+    if (typeof shadow === 'string') {
+        return attachShadow(host, shadow);
+    }
+    if (typeof shadow === 'object' && shadow !== null && 'mode' in shadow) {
+        const config = shadow;
+        const root = attachShadow(host, config.mode);
+        if (config.styles && typeof CSSStyleSheet !== 'undefined') {
+            try {
+                const sheet = new CSSStyleSheet();
+                sheet.replaceSync(config.styles);
+                root.adoptedStyleSheets = [sheet];
+            }
+            catch {
+            }
+        }
+        return root;
+    }
+    return undefined;
+}
+/**
+ * Applies attributes, namespaced attributes, and dataset to an element.
+ *
+ * @private
+ * @ignore
+ * @function applyAttributes
+ * @param {HTMLElement|SVGElement} element - The target element.
+ * @param {Object} data - Element configuration with attr/attrNS/dataset arrays.
+ */
+function applyAttributes(element, data) {
+    if (data.attr?.length) {
+        setAttr({ element, attrs: data.attr });
+    }
+    if ('attrNS' in data && data.attrNS?.length) {
+        setAttrNS({ element, attrs: data.attrNS });
+    }
+    if (data.dataset?.length) {
+        setData({ element, dataset: data.dataset });
+    }
+}
+/**
+ * Creates an HTML element and appends it to a parent.
+ * Supports attribute assignment, dataset configuration with automatic
+ * store registration, and optional shadow DOM creation.
+ *
+ * @function createHTMLElement
+ * @param {Object} [options] - Element creation options.
+ * @param {HTMLElement|ShadowRoot} [options.parent=document.body] - Parent element to append to.
+ * @param {Object} options.element - Element definition with type, attr, and dataset arrays.
+ * @param {string} options.element.type - HTML tag name (e.g., 'div', 'button').
+ * @param {Array} [options.element.attr] - Array of {name, value} attribute pairs.
+ * @param {Array} [options.element.dataset] - Array of {name, value} dataset pairs.
+ * @param {ShadowConfig} [options.shadow] - Shadow DOM configuration.
+ * @returns {HTMLElement|ShadowRoot|undefined} The created element, shadow root, or undefined on error.
+ */
+function createHTMLElement(data = {}) {
+    try {
+        const { parent, element: elementData, shadow } = data;
+        const element = document.createElement(elementData.type);
+        applyAttributes(element, elementData);
+        const targetParent = parent ?? document.body;
+        if (targetParent instanceof HTMLElement || targetParent instanceof SVGElement || targetParent instanceof ShadowRoot) {
+            targetParent.appendChild(element);
+        }
+        if (shadow && element.dataset?.state) {
+            const shadowRoot = createShadowFromConfig(element, shadow);
+            if (shadowRoot)
+                return shadowRoot;
+        }
+        return element;
+    }
+    catch (err) {
+        console.error(err);
+        return undefined;
+    }
+}
+/**
+ * Creates an SVG element and appends it to a parent.
+ * Supports standard and namespaced attributes, and dataset configuration.
+ *
+ * @function createSVGElement
+ * @param {Object} [options] - Element creation options.
+ * @param {SVGElement|HTMLElement} [options.parent] - Parent element to append to.
+ * @param {Object} options.element - Element definition.
+ * @param {string} options.element.type - SVG tag name (e.g., 'circle', 'rect').
+ * @param {Array} [options.element.attr] - Array of {name, value} attribute pairs.
+ * @param {Array} [options.element.attrNS] - Array of {name, value} namespaced attribute pairs.
+ * @param {Array} [options.element.dataset] - Array of {name, value} dataset pairs.
+ * @returns {SVGElement|undefined} The created SVG element, or undefined on error.
+ */
+function createSVGElement(data = {}) {
+    try {
+        const { parent, element: elementData } = data;
+        const element = document.createElementNS('http://www.w3.org/2000/svg', elementData.type);
+        applyAttributes(element, elementData);
+        if (parent) {
+            if (parent instanceof HTMLElement || parent instanceof SVGElement) {
+                parent.appendChild(element);
+            }
+        }
+        return element;
+    }
+    catch (err) {
+        console.error(err);
+        return undefined;
+    }
+}/**
+ * @module DomStructModule
+ * @description
+ * Provides declarative DOM tree construction from structured data (ElementStruct)
+ * and element removal with recursive event listener cleanup.
+ * Integrates with EventModule via the extension system for declarative event binding.
+ */
+/**
+ * Creates an event listener on a DOM element based on struct configuration.
+ * Reads the `EventModule` from registered extensions, looks up the action
+ * by name in `EventActions`, and attaches the listener via `addEventToStore`.
+ *
+ * @private
+ * @ignore
+ * @function createEventElement
+ * @param {Object} data - Event binding data.
+ * @param {ElementStruct} data.struct - The element struct containing event config.
+ * @param {Element} data.element - The DOM element to attach the listener to.
+ */
+function createEventElement(data) {
+    const { struct, element } = data;
+    const eventModule = getAnyExtension();
+    if (!eventModule)
+        return;
+    if (struct.event?.action && struct.event?.type) {
+        const eventActions = eventModule.EventActions;
+        if (eventActions && eventActions[struct.event.action]) {
+            const eventStoreSchema = {
+                element,
+                type: struct.event.type,
+                handler: eventActions[struct.event.action],
+            };
+            if (struct.event.node)
+                eventStoreSchema.nodeId = struct.event.node;
+            const addEvent = eventModule.addEventToStore;
+            addEvent(eventStoreSchema);
+        }
+    }
+}
+/**
+ * Builds a DOM tree from a structured definition.
+ * Creates the root element, applies attributes, text, HTML content,
+ * optional event bindings, and recursively creates children.
+ *
+ * @function createFromStruct
+ * @param {Object} data - Struct data.
+ * @param {ElementStruct} data.struct - The element structure definition.
+ * @param {HTMLElement|ShadowRoot} [data.parent=document.body] - Parent element to append to.
+ * @returns {Element|false} The created element, or false on failure.
+ */
+function createFromStruct(data) {
+    try {
+        if (typeof data !== 'object' || !data)
+            return false;
+        const { struct, parent = document.body } = data;
+        if (!struct?.element)
+            return false;
+        const isSvg = struct.type && struct.type.toLowerCase() === 'svg';
+        const attrArray = struct.attr ? Object.entries(struct.attr).map(([name, value]) => ({ name, value })) : [];
+        const datasetArray = struct.dataset ? Object.entries(struct.dataset).map(([name, value]) => ({ name, value })) : [];
+        let element;
+        if (isSvg) {
+            const attrNSArray = struct.attrNS ? Object.entries(struct.attrNS).map(([name, value]) => ({ name, value })) : [];
+            const svgData = {
+                parent: parent,
+                element: {
+                    type: struct.element,
+                    attr: attrArray,
+                    attrNS: attrNSArray,
+                    dataset: datasetArray,
+                },
+            };
+            element = createSVGElement(svgData);
+        }
+        else {
+            const htmlData = {
+                parent: parent,
+                element: {
+                    type: struct.element,
+                    attr: attrArray,
+                    dataset: datasetArray,
+                },
+                shadow: struct.shadow,
+            };
+            const result = createHTMLElement(htmlData);
+            if (result instanceof ShadowRoot) {
+                element = result.host;
+            }
+            else {
+                element = result;
+            }
+        }
+        if (!element)
+            return false;
+        if (struct.text !== undefined) {
+            element.textContent = struct.text;
+        }
+        if (struct.html !== undefined) {
+            element.innerHTML = struct.html;
+        }
+        createEventElement({ struct, element });
+        if (struct.children && struct.children.length > 0) {
+            for (const child of struct.children) {
+                createFromStruct({ struct: child, parent: element });
+            }
+        }
+        return element;
+    }
+    catch (err) {
+        console.error(err);
+        return false;
+    }
+}
+/**
+ * Attempts to clean up an element from the store or its event listeners.
+ * If the element has a `data-state` attribute, it removes it from the store
+ * (with event cleanup if EventModule is registered). Otherwise, if EventModule
+ * is available, it removes all event listeners from the element.
+ *
+ * @private
+ * @ignore
+ * @function removeElementFromStoreOrEvents
+ * @param {Element} element - The element to clean up.
+ * @returns {boolean} - True if cleanup was performed.
+ */
+function removeElementFromStoreOrEvents(element) {
+    try {
+        const eventModule = getAnyExtension();
+        const htmlElement = element;
+        if (htmlElement.dataset?.state) {
+            removeElementFromStore({ key: htmlElement.dataset.state, mode: eventModule ? 1 : 2, EventModule: eventModule });
+            return true;
+        }
+        if (eventModule && typeof eventModule.removeAllEventsFromStore === 'function') {
+            const removeAll = eventModule.removeAllEventsFromStore;
+            removeAll(element);
+            return true;
+        }
+    }
+    catch {
+    }
+    return false;
+}
+/**
+ * Removes a DOM element and recursively cleans up its children.
+ * For each element with `[listener="true"]`, calls `removeAllEventsFromStore`.
+ * For each element with `[data-state]`, removes from the element store.
+ * Finally removes the element from the DOM.
+ *
+ * @function removeElement
+ * @param {Element} element - The element to remove.
+ */
+function removeElement(element) {
+    if (!element)
+        return;
+    removeElementFromStoreOrEvents(element);
+    const listeners = element.querySelectorAll('[listener="true"]');
+    for (let i = listeners.length - 1; i >= 0; i--) {
+        const item = listeners[i];
+        if (item) {
+            removeElementFromStoreOrEvents(item);
+        }
+    }
+    const withState = element.querySelectorAll('[data-state]');
+    for (let i = withState.length - 1; i >= 0; i--) {
+        const item = withState[i];
+        if (item) {
+            const eventModule = getAnyExtension();
+            removeElementFromStore({ key: item.dataset.state, mode: eventModule ? 1 : 2, EventModule: eventModule });
+            item.removeAttribute('data-state');
+        }
+    }
+    element.remove();
+}/**
+ * @module DomModule
+ * @description
+ * Central module for DOM manipulation in @simplybuilder/core. Provides element
+ * creation, attribute management, declarative DOM tree construction, element
+ * removal with recursive event cleanup, and an extension system for optional
+ * integration with @simplybuilder/core-event.
+ */
+const name = "SBCoreDom";
+const version = "2.0.0";
+/**
+ * Frozen singleton combining all DOM manipulation capabilities.
+ * Pass `domModuleExtends()` to register an EventModule for declarative
+ * event binding in `createFromStruct` and automatic listener cleanup in `removeElement`.
+ *
+ * @type {Object}
+ * @property {string} name - Module identifier.
+ * @property {string} version - Module version.
+ * @property {Function} domModuleExtends - Register an extension module.
+ * @property {Function} createHTMLElement - Create and append HTML elements.
+ * @property {Function} createSVGElement - Create and append SVG elements.
+ * @property {Function} addElementToStore - Store element reference by key.
+ * @property {Function} getElementFromStore - Retrieve stored element.
+ * @property {Function} removeElementFromStore - Remove element from store.
+ * @property {Function} createFromStruct - Build DOM tree from struct definition.
+ * @property {Function} removeElement - Remove element with listener cleanup.
+ */
+const DomModule = Object.freeze({
+    name,
+    version,
+    domModuleExtends,
+    createHTMLElement,
+    createSVGElement,
+    addElementToStore,
+    getElementFromStore,
+    removeElementFromStore,
+    createFromStruct,
+    removeElement,
+});export{DomModule,addElementToStore,clearStore,createEventElement,createFromStruct,createHTMLElement,createSVGElement,DomModule as default,domModuleExtends,getElementFromStore,name,removeElement,removeElementFromStore,setAttr,setAttrNS,setData,validVersionSupport,version};
+/*! https://simplybuilder.github.io */

package/lib/store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module DomStoreModule
+ * @description
+ * Key-value store for DOM element references. Elements can be registered
+ * by a string key and retrieved or removed later. Supports two removal modes:
+ * mode 1 (with EventModule cleanup) and mode 2 (store only).
+ */
+/**
+ * Registers a DOM element in the store under a unique key.
+ * If the key already exists, the operation is silently ignored.
+ *
+ * @function addElementToStore
+ * @param {Object} data - Registration data.
+ * @param {string} data.key - Unique identifier for the element.
+ * @param {Element} data.value - The DOM element to store.
+ */
+declare function addElementToStore(data: {
+    key: string;
+    value: Element;
+}): void;
+/**
+ * Retrieves a stored DOM element by its key.
+ *
+ * @function getElementFromStore
+ * @param {string} key - The element's unique key.
+ * @returns {Element|undefined} - The stored element, or undefined.
+ */
+declare function getElementFromStore(key: string): Element | undefined;
+/**
+ * Removes a DOM element from the store by its key.
+ * In mode 1 (default), calls `EventModule.removeAllEventsFromStore`
+ * before deleting. In mode 2, deletes from store only.
+ *
+ * @function removeElementFromStore
+ * @param {Object} data - Removal data.
+ * @param {string} data.key - The element's unique key.
+ * @param {number} [data.mode=1] - Removal mode: 1 with event cleanup, 2 store only.
+ * @param {Object} [data.EventModule] - Optional EventModule for listener cleanup.
+ * @returns {boolean} - True if the element was found and removed.
+ */
+declare function removeElementFromStore(data: {
+    key: string;
+    mode?: number;
+    EventModule?: Record<string, unknown>;
+}): boolean;
+/**
+ * Removes all entries from the store. Used for testing.
+ *
+ * @function clearStore
+ */
+declare function clearStore(): void;
+export { addElementToStore, getElementFromStore, removeElementFromStore, clearStore, };