@simplybuilder/core-dom 2.0.0

package/lib/struct.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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.
+ */
+import type { ElementStruct } from './types.js';
+/**
+ * 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.
+ */
+declare function createEventElement(data: {
+    struct: ElementStruct;
+    element: Element;
+}): void;
+/**
+ * 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.
+ */
+declare function createFromStruct(data: {
+    struct: ElementStruct;
+    parent?: HTMLElement | ShadowRoot;
+}): Element | 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.
+ */
+declare function removeElementFromStoreOrEvents(element: Element): boolean;
+/**
+ * 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.
+ */
+declare function removeElement(element: Element): void;
+export { createFromStruct, removeElement, createEventElement, removeElementFromStoreOrEvents };

package/lib/types.d.ts

@@ -0,0 +1,58 @@
+export interface ShadowConfigString {
+    mode: 'open' | 'closed';
+}
+export interface ShadowConfigObject {
+    mode: 'open' | 'closed';
+    styles?: string;
+}
+export type ShadowConfig = ShadowConfigString | ShadowConfigObject | string;
+export interface EventStruct {
+    type: string;
+    action: string;
+    node?: string;
+}
+export interface ElementStruct {
+    element: string;
+    type?: string;
+    attr?: Record<string, string>;
+    attrNS?: Record<string, string>;
+    dataset?: Record<string, string>;
+    text?: string;
+    html?: string;
+    shadow?: ShadowConfig;
+    event?: EventStruct;
+    children?: ElementStruct[];
+}
+export interface CreateHTMLElementOptions {
+    parent?: HTMLElement | ShadowRoot;
+    element: {
+        type: string;
+        attr?: Array<{
+            name: string;
+            value: string;
+        }>;
+        dataset?: Array<{
+            name: string;
+            value: string;
+        }>;
+    };
+    shadow?: ShadowConfig;
+}
+export interface CreateSVGElementOptions {
+    parent?: HTMLElement | SVGElement;
+    element: {
+        type: string;
+        attr?: Array<{
+            name: string;
+            value: string;
+        }>;
+        attrNS?: Array<{
+            name: string;
+            value: string;
+        }>;
+        dataset?: Array<{
+            name: string;
+            value: string;
+        }>;
+    };
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@simplybuilder/core-dom",
+  "version": "2.0.0",
+  "main": "lib/main.commonjs.min.cjs",
+  "module": "lib/main.esm.min.mjs",
+  "types": "lib/core-dom.d.ts",
+  "typings": "lib/core-dom.d.ts",
+  "exports": {
+    "./commonjs-module": {
+      "require": "./lib/main.commonjs.min.cjs"
+    },
+    "./esm-module": {
+      "import": "./lib/main.esm.min.mjs"
+    },
+    "./dts": {
+      "types": "./lib/core-dom.d.ts"
+    },
+    "./core-dom": {
+      "types": "./lib/core-dom.d.ts"
+    },
+    ".": {
+      "types": "./lib/core-dom.d.ts",
+      "import": "./lib/main.esm.min.mjs",
+      "require": "./lib/main.commonjs.min.cjs"
+    }
+  },
+  "files": [
+    "AUTHORS",
+    "CONTRIBUTING.md",
+    "GOVERNANCE.md",
+    "MAINTAINERS.md",
+    "lib/main.commonjs.cjs",
+    "lib/main.commonjs.min.cjs",
+    "lib/main.esm.min.mjs",
+    "lib/main.esm.mjs",
+    "lib/**/*.d.ts"
+  ],
+  "homepage": "https://simplybuilder.github.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SimplyBuilder/sb-core-v2.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SimplyBuilder/sb-core-v2/issues"
+  },
+  "author": "Jamil Services <jamilservicos@gmail.com> (https://github.com/jamilservicos)",
+  "funding": [
+    {
+      "type": "kofi",
+      "url": "https://ko-fi.com/juliojamil"
+    },
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/jamilservicos"
+    }
+  ],
+  "devDependencies": {
+    "jsdom": "^26.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "jamilservicos",
+    "jamilservices",
+    "node",
+    "nodejs",
+    "node.js",
+    "javascript",
+    "typescript",
+    "simply-builder",
+    "simplybuilder",
+    "simply",
+    "builder",
+    "module",
+    "core",
+    "front",
+    "frontend",
+    "front-end",
+    "dom"
+  ],
+  "scripts": {
+    "clean": "rm -rf lib && rm -rf audit",
+    "build:js": "tsc -p tsconfig-audit.json",
+    "build:types": "tsc -p tsconfig-types.json",
+    "build:pre": "pnpm run clean && pnpm run build:js && pnpm run build:types",
+    "build": "pnpm run build:pre && rollup -c ./rollup.config.js ",
+    "test": "vitest run",
+    "publish:pre": "pnpm build && pnpm test",
+    "publish:pack": "pnpm build && tar tvf $(npm pack)"
+  }
+}