@simplybuilder/core-dom 2.0.0

package/AUTHORS

@@ -0,0 +1,2 @@
+Jamil Services <jamilservices@gmail.com>
+Jamil Services <jamilservicos@gmail.com>

package/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+### Contributing to `@simplybuilder/core-dom`
+Thank you for considering contributing to `@simplybuilder/core-dom`!     
+This document contains a set of guidelines for contributing to `@simplybuilder/core-dom`.      
+These are guidelines, not rules. Use your best judgment and feel free to propose changes to this document in a pull request.
+
+
+
+#### How to Contribute
+**Reporting Bugs**     
+Before creating a bug report, please check if it has already been reported. If you find a bug that has not yet been reported, create an issue using the provided template.
+
+**When creating a bug report, make sure to include:**
+- A concise description of the issue
+- Steps to reproduce the issue
+- Expected behavior
+- Observed behavior
+- Any additional information that may be helpful
+
+**Suggesting Improvements**      
+Improvements are always welcome, whether in the form of new features or enhancements to existing ones. Feel free to create an issue to discuss your ideas.
+
+#### Pull Requests
+**Want to submit your own code? Great! Here are some simple steps to get started:**
+
+- Fork the project: This allows you to have your own copy of the project to work on.
+- Create a branch: Use a descriptive name for your branch, such as feature/new_feature_name or bugfix/bug_description.
+- Make your changes: Make sure to follow the project's coding guidelines.
+- Test your changes: Run the existing tests and add new ones if you are introducing new features.
+- Submit a Pull Request: Include a clear description of what is being proposed and any other relevant information.
+
+#### Code of Conduct
+All contributors are expected to follow our Code of Conduct. Please read it before contributing.
+
+#### Questions?
+If you have any questions or need assistance, feel free to create an issue.

package/GOVERNANCE.md

@@ -0,0 +1,10 @@
+The `@simplybuilder/core-dom` project is governed by [@jamilservicos](https://github.com/jamilservicos) which is responsible for high-level guidance of the project.
+
+**The [@jamilservicos](https://github.com/jamilservicos) has final authority over this project including:**
+
+* Technical direction
+* Project governance and process (including this policy)
+* Contribution policy
+* GitHub repository hosting
+* Conduct guidelines
+* Maintaining the list of additional Collaborators

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Simply Builder by Jamil Services
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MAINTAINERS.md

@@ -0,0 +1 @@
+[@jamilservicos](https://github.com/jamilservicos) is the main/default maintainer

package/README.md

@@ -0,0 +1,74 @@
+# @simplybuilder/core-dom
+
+DOM manipulation module for @simplybuilder/core. Provides element creation, attribute management, DOM tree construction, and element removal with optional event module integration.
+
+## Installation
+
+```bash
+pnpm add @simplybuilder/core-dom
+```
+
+## Usage
+
+```typescript
+import { createHTMLElement, createSVGElement, createFromStruct, removeElement, domModuleExtends } from '@simplybuilder/core-dom';
+
+// Simple element creation
+const btn = createHTMLElement({
+  element: { type: 'button', attr: [{ name: 'class', value: 'primary' }] },
+});
+
+// Nested DOM from struct
+const section = createFromStruct({
+  struct: {
+    element: 'section',
+    dataset: { state: 'main' },
+    children: [
+      { element: 'h1', text: 'Title' },
+      { element: 'p', text: 'Content' },
+    ],
+  },
+});
+
+// Element removal with cleanup
+removeElement(section);
+// → removes from store, cleans up event listeners, removes from DOM
+
+// Integration with event module (optional, zero dependency)
+import { eventRegister, addEventToStore, removeAllEventsFromStore } from '@simplybuilder/core-event';
+
+domModuleExtends({
+  name: 'SBCoreEvent',
+  version: '2.0.0',
+  EventActions: { /* registered actions */ },
+  addEventToStore,
+  removeAllEventsFromStore,
+});
+
+// Now createFromStruct processes struct.event config
+const el = createFromStruct({
+  struct: { element: 'button', event: { type: 'click', action: 'handleClick' } },
+});
+```
+
+## API
+
+- `domModuleExtends(data)` — Register an extension module (e.g., EventModule) for declarative event binding
+- `createHTMLElement(options)` — Create HTML elements with attributes, dataset, shadow DOM
+- `createSVGElement(options)` — Create SVG elements with namespaced attributes
+- `createFromStruct(struct)` — Build nested DOM trees from struct with optional event binding
+- `removeElement(element)` — Remove element, clean up store and event listeners recursively
+- `addElementToStore({ key, value })` — Store element reference by key
+- `getElementFromStore(key)` — Retrieve stored element by key
+- `removeElementFromStore({ key, mode, EventModule? })` — Remove from store (mode 1: with event cleanup, mode 2: store only)
+- `setAttr({ element, attrs })` — Set attributes on element
+- `setAttrNS({ element, attrs })` — Set namespaced attributes
+- `setData({ element, dataset })` — Set dataset properties
+- `DomModule` — Frozen singleton with all capabilities
+
+## Build from Source
+
+```bash
+pnpm install
+pnpm build
+```

package/lib/attributes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module DomAttributeModule
+ * @description
+ * Utility functions for setting standard and namespaced attributes on DOM elements.
+ */
+interface SetAttrData {
+    element: HTMLElement | SVGElement;
+    attrs: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function setAttr(data: SetAttrData): void;
+/**
+ * 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.
+ */
+export declare function setAttrNS(data: SetAttrData): void;
+export {};

package/lib/core-dom.d.ts

@@ -0,0 +1 @@
+export { name, version, DomModule, domModuleExtends, getElementFromStore, createFromStruct, removeElement } from "./main";

package/lib/creator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module DomComponentModule
+ * @description
+ * Provides functions for creating and appending HTML and SVG elements.
+ * Handles attribute assignment, dataset configuration, and shadow DOM creation.
+ */
+import type { CreateHTMLElementOptions, CreateSVGElementOptions } from './types.js';
+/**
+ * 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.
+ */
+export declare function createHTMLElement(data?: CreateHTMLElementOptions): HTMLElement | ShadowRoot | 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.
+ */
+export declare function createSVGElement(data?: CreateSVGElementOptions): SVGElement | undefined;

package/lib/dataset.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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.
+ */
+interface SetDataData {
+    element: HTMLElement | SVGElement;
+    dataset: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * 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.
+ */
+declare function setData(data: SetDataData): void;
+export { setData };

package/lib/extension.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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.
+ */
+interface ModuleData {
+    name: string;
+    version: string;
+    [key: string]: unknown;
+}
+/**
+ * Internal store for module metadata, registered extensions, and version constraints.
+ *
+ * @private
+ * @ignore
+ * @type {Object}
+ */
+declare const internalStore: {
+    app: {
+        name: string;
+        version: string;
+    };
+    register: Record<string, ModuleData>;
+    allow: Record<string, {
+        major?: number;
+        minor?: number;
+        patch?: number;
+    }>;
+    clearExtensions: () => void;
+};
+/**
+ * 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.
+ */
+declare function validVersionSupport(data: ModuleData): boolean;
+/**
+ * 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.
+ */
+declare function domModuleExtends(data: ModuleData): boolean;
+/**
+ * Retrieves a registered extension module by name.
+ *
+ * @function getExtension
+ * @param {string} name - The module identifier.
+ * @returns {Object|undefined} - The registered module data, or undefined.
+ */
+declare function getExtension(name: string): ModuleData | undefined;
+/**
+ * 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.
+ */
+declare function getAnyExtension(): ModuleData | undefined;
+/**
+ * Removes all registered extensions. Used for testing.
+ *
+ * @function clearExtensions
+ */
+declare function clearExtensions(): void;
+export { internalStore, validVersionSupport, domModuleExtends, getExtension, getAnyExtension, clearExtensions, };
+export type { ModuleData };