@zyrab/domo 1.2.1 → 1.4.0

package/{LICENSE → LICENSE.md}

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Zyrab
-
-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.
+MIT License
+
+Copyright (c) 2026 Zyrab
+
+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/README.md

@@ -0,0 +1,88 @@
+# @zyrab/domo
+
+**Small, Fast, and Chainable.**
+
+`domo` is a minimalist, industrial-strength DOM builder and UI micro-framework designed for developers who value performance, zero-boilerplate, and elegant APIs. It provides a fluent, chainable interface for building both dynamic browser applications and high-performance static sites.
+
+---
+
+## Why Domo?
+
+In a world of heavy frameworks, `domo` returns to the fundamentals while providing modern features for the SSG era.
+
+- **Fluent API**: Build complex structures with a natural, chainable syntax.
+- **Dual-Entry Architecture**: Optimized builds for both Client and Server. The client bundle contains 0% string-building logic, while the server bundle acts as a high-speed metadata collector.
+- **Zero-Branching**: No more `if (isServer)` in your components. Environment-aware modules handle the complexity for you.
+- **SSG Native**: Deeply integrated with `@zyrab/domo-ssg`. Automatically collects events, refs, and state during the render pass to enable seamless hydration-free interactivity.
+- **Microscopic Footprint**: Designed to be small enough to stay out of your way, yet powerful enough to build entire applications.
+
+---
+
+## Installation
+
+```bash
+pnpm add @zyrab/domo
+```
+
+---
+
+## Usage
+
+### Basic Component
+```javascript
+import Domo from '@zyrab/domo';
+
+const card = Domo('div').cls('card')
+  .child([
+    Domo('h1').txt('Product Name').css({ color: 'blue' }),
+    Domo('p').txt('This is a description.'),
+    Domo('button').txt('Add to Cart').on('click', () => alert('Added!'))
+  ])
+  .build();
+
+document.body.appendChild(card);
+```
+
+### Advanced State & Interactivity
+Domo handles state synchronization between Server and Client via the `.state()` method.
+
+```javascript
+import Domo from '@zyrab/domo';
+
+export default function Counter(initial = 0) {
+  return Domo('div').cls('counter')
+    .state({ count: initial })
+    .child([
+      Domo('span').txt(`Count: ${initial}`).id('display'),
+      Domo('button').txt('+').on('click', (e) => {
+        // Access state via Domo runtime...
+      })
+    ]);
+}
+```
+
+### Server-Side Rendering (SSG/SSR)
+On the server, `domo` generates clean HTML while capturing metadata for the hydration bridge.
+
+```javascript
+import Domo from '@zyrab/domo';
+
+// Identical code works on the server!
+const html = Domo('div').txt('Hello from Server').build();
+console.log(html); // "<div>Hello from Server</div>"
+```
+
+---
+
+## Architecture
+
+Domo uses a **Layered Inheritance System** instead of dynamic mixins, ensuring maximum compatibility with modern bundlers and IDEs.
+
+- **Client Pass**: Uses native `document.createElement`, `classList`, and `addEventListener`.
+- **Server Pass**: Uses a lightweight "Virtual Element" (`vel`) schema and collects metadata (events, refs, state) for the SSG to generate optimal client-side bridge logic.
+
+---
+
+## License
+
+MIT © [Zyrab](https://github.com/zyrab) - see the [LICENSE.md](LICENSE.md) file for details.

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@zyrab/domo",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Minimalist DOM builder and chaining-friendly micro-framework with router support.",
-  "main": "./src/domo.js",
+  "main": "./src/index.js",
   "type": "module",
   "exports": {
-    "import": "./src/domo.js",
-    "default": "./src/domo.js"
+    "import": "./src/index.js",
+    "default": "./src/index.js"
   },
   "author": "Zyrab",
   "license": "MIT",
   "files": [
-    "src/"
+    "src/",
+    "README.md",
+    "LICENSE.md"
   ],
   "keywords": [
     "dom",

package/src/client/base.client.js

@@ -0,0 +1,37 @@
+/**
+ * @class BaseClient
+ * @description Foundational class for Client-side Domo elements.
+ */
+class BaseClient {
+  /**
+   * @property {HTMLElement} element - The actual DOM element.
+   */
+  element;
+
+  /**
+   * @property {boolean} _isDomo - Flag to identify Domo instances.
+   */
+  _isDomo = true;
+
+  /**
+   * Creates an instance of BaseClient.
+   * @param {string} [el="div"] - The HTML tag name.
+   */
+  constructor(el = "div") {
+    this.element = document.createElement(String(el || "div").toLowerCase());
+  }
+  island(enabled = false) {
+    return this;
+  }
+  /**
+   * In browser context, passes the actual DOM element to the callback.
+   * @param {function(HTMLElement): void} callback
+   * @returns {this}
+   */
+  ref(callback) {
+    if (typeof callback === "function") callback(this.element);
+    return this;
+  }
+}
+
+export default BaseClient;

package/src/client/builder.client.js

@@ -0,0 +1,17 @@
+import ChildrenClient from "./children.client.js";
+
+/**
+ * @class BuilderClient
+ * @extends ChildrenClient
+ */
+class BuilderClient extends ChildrenClient {
+  /**
+   * Finalizes the element construction and returns the native DOM element.
+   * @returns {HTMLElement}
+   */
+  build() {
+    return this.element;
+  }
+}
+
+export default BuilderClient;

package/src/client/children.client.js

@@ -0,0 +1,72 @@
+import EventsClient from "./events.client.js";
+
+/**
+ * @class ChildrenClient
+ * @extends EventsClient
+ */
+class ChildrenClient extends EventsClient {
+  _handleElementInstance(element) {
+    if (element && element._isDomo) return element.build();
+    if (element instanceof DocumentFragment || element instanceof Node) return element;
+    if (typeof element === "string" || typeof element === "number") {
+      return document.createTextNode(String(element));
+    }
+    return document.createTextNode(`⚠ Invalid child: ${String(element)}`);
+  }
+
+  child(children = []) {
+    const flattenedChildren = Array.isArray(children) ? children.flat() : [children];
+    flattenedChildren.forEach((child) => {
+      this.element.appendChild(this._handleElementInstance(child));
+    });
+    return this;
+  }
+
+  append(children = []) {
+    return this.child(children);
+  }
+
+  appendTo(target) {
+    const targetNode = target && target._isDomo ? target.element : target;
+    if (targetNode instanceof Node) {
+      targetNode.appendChild(this.element);
+    }
+    return this;
+  }
+
+  parent(target) {
+    return this.appendTo(target);
+  }
+
+  clear() {
+    this.element.replaceChildren();
+    return this;
+  }
+
+  replace(child, newChild) {
+    const resolvedNew = this._handleElementInstance(newChild);
+    if (child === this.element) {
+      this.element.replaceWith(resolvedNew);
+      this.element = resolvedNew;
+    } else if (this.element.contains(child)) {
+      child.replaceWith(resolvedNew);
+    }
+    return this;
+  }
+
+  show(visible = true, displayValue = "block") {
+    this.element.style.display = visible ? displayValue : "none";
+    return this;
+  }
+
+  if(condition) {
+    if (!condition) {
+      return new this.constructor("if")
+        .attr({ hidden: true })
+        .data({ if: this.element.tagName.toLowerCase() });
+    }
+    return this;
+  }
+}
+
+export default ChildrenClient;

package/src/client/classes.client.js

@@ -0,0 +1,36 @@
+import PropertiesClient from "./properties.client.js";
+
+/**
+ * @class ClassesClient
+ * @extends PropertiesClient
+ */
+class ClassesClient extends PropertiesClient {
+  /**
+   * Normalizes various inputs into a clean array of class names.
+   * @private
+   */
+  _parseClassList(input) {
+    return Array.isArray(input) ? input.filter(Boolean) : String(input).split(" ").filter(Boolean);
+  }
+
+  cls(classes) {
+    if (!classes) return this;
+    const clsList = this._parseClassList(classes);
+    this.element.classList.add(...clsList);
+    return this;
+  }
+
+  rmvCls(classes) {
+    if (classes) {
+      this.element.classList.remove(...this._parseClassList(classes));
+    }
+    return this;
+  }
+
+  tgglCls(className, force) {
+    this.element.classList.toggle(className, force);
+    return this;
+  }
+}
+
+export default ClassesClient;

package/src/client/domo.client.js

@@ -0,0 +1,24 @@
+import BuilderClient from "./builder.client.js";
+
+/**
+ * @class DomoClient
+ * @extends BuilderClient
+ * @description Main Domo class for the Browser environment.
+ */
+class DomoClient extends BuilderClient {
+  constructor(el = "div") {
+    super(el);
+  }
+}
+
+/**
+ * Factory function for Browser Domo elements.
+ * @param {string} [el="div"]
+ * @returns {DomoClient}
+ */
+function Domo(el = "div") {
+  return new DomoClient(el);
+}
+
+export { DomoClient };
+export default Domo;

package/src/client/events.client.js

@@ -0,0 +1,51 @@
+import ClassesClient from "./classes.client.js";
+
+/**
+ * @class EventsClient
+ * @extends ClassesClient
+ */
+class EventsClient extends ClassesClient {
+  /**
+   * Adds event listeners to the element.
+   */
+  on(eventMapOrName, callback, options = {}) {
+    if (!eventMapOrName) return this;
+
+    if (typeof eventMapOrName === "object" && eventMapOrName !== null) {
+      for (const [event, value] of Object.entries(eventMapOrName)) {
+        if (typeof value === "function") {
+          this.element.addEventListener(event, value);
+        } else if (Array.isArray(value)) {
+          const [cb, opts] = value;
+          this.element.addEventListener(event, cb, opts);
+        }
+      }
+    } else if (typeof callback === "function") {
+      this.element.addEventListener(eventMapOrName, callback, options);
+    }
+    return this;
+  }
+
+  _handleClosest(e, map) {
+    for (const [selector, handler] of Object.entries(map)) {
+      const match = e.target.closest(selector);
+      if (match) handler(e, match);
+    }
+  }
+
+  onClosest(event, selectors = {}, options = {}) {
+    return this.on(event, (e) => this._handleClosest(e, selectors), options);
+  }
+
+  _handleMatches(e, map) {
+    for (const [selector, handler] of Object.entries(map)) {
+      if (e.target.matches(selector)) handler(e, e.target);
+    }
+  }
+
+  onMatch(event, selectors = {}, options = {}) {
+    return this.on(event, (e) => this._handleMatches(e, selectors), options);
+  }
+}
+
+export default EventsClient;

package/src/client/properties.client.js

@@ -0,0 +1,78 @@
+import BaseClient from "./base.client.js";
+
+const _stateMap = new WeakMap();
+
+/**
+ * @class PropertiesClient
+ * @extends BaseClient
+ */
+class PropertiesClient extends BaseClient {
+  /**
+   * Sets a property on the element.
+   * @protected
+   * @param {string} key
+   * @param {*} val
+   * @returns {this}
+   */
+  _set(key, val) {
+    if (val === undefined) return this;
+    this.element[key] = val;
+    return this;
+  }
+
+  id(id) {
+    return this._set("id", id);
+  }
+
+  val(value) {
+    return this._set("value", value);
+  }
+
+  txt(text) {
+    return this._set("textContent", text);
+  }
+
+  attr(attributes = {}) {
+    for (const [key, value] of Object.entries(attributes)) {
+      if (typeof value === "boolean") {
+        value ? this.element.setAttribute(key, "") : this.element.removeAttribute(key);
+      } else if (value != null) {
+        this.element.setAttribute(key, value);
+      }
+    }
+    return this;
+  }
+
+  tgglAttr(attrName, force) {
+    if (typeof force === "boolean") {
+      force ? this.element.setAttribute(attrName, "") : this.element.removeAttribute(attrName);
+    } else {
+      this.element.hasAttribute(attrName) ? this.element.removeAttribute(attrName) : this.element.setAttribute(attrName, "");
+    }
+    return this;
+  }
+
+  data(data = {}) {
+    Object.entries(data).forEach(([key, val]) => {
+      this.element.dataset[key] = val;
+    });
+    return this;
+  }
+
+  css(styles = {}) {
+    Object.assign(this.element.style, styles);
+    return this;
+  }
+
+  /**
+   * Stores state object in a WeakMap for the client runtime.
+   * @param {object} obj
+   * @returns {this}
+   */
+  state(obj) {
+    _stateMap.set(this.element, obj);
+    return this;
+  }
+}
+
+export default PropertiesClient;

package/src/index.js

@@ -0,0 +1,14 @@
+import DomoClientFactory, { DomoClient } from "./client/domo.client.js";
+import DomoServerFactory, { DomoServer } from "./server/domo.server.js";
+
+const isServer = typeof document === "undefined";
+
+/**
+ * The main Domo factory function.
+ * Automatically resolves to DomoClient in the browser and DomoServer in Node.js/SSG environments.
+ * @type {typeof DomoClientFactory}
+ */
+const Domo = isServer ? DomoServerFactory : DomoClientFactory;
+
+export default Domo;
+export { DomoClient, DomoServer };

package/src/server/base.server.js

@@ -0,0 +1,121 @@
+import { fileURLToPath } from "url";
+/**
+ * @class BaseServer
+ * @description Foundational class for Server-side (Virtual) Domo elements.
+ * Acts as a Metadata Collector for the SSG.
+ */
+class BaseServer {
+  /**
+   * @property {object} element - The virtual representation of the element.
+   */
+  element;
+
+  /**
+   * @property {boolean} _isDomo - Flag to identify Domo instances.
+   */
+  _isDomo = true;
+
+  /**
+   * Creates an instance of BaseServer.
+   * @param {string} [el="div"] - The HTML tag name.
+   */
+  constructor(el = "div") {
+    this.element = {
+      _tag: el,
+      _attr: {},
+      _cls: [],
+      _data: {},
+      _css: {},
+      _child: [],
+      _events: [],
+      _refs: [],
+      _island: false,
+      _state: {},
+      __file: null,
+    };
+  }
+
+  /**
+   * Manually mark this element/component as an island.
+   * This signals the SSG to bundle the Domo client runtime.
+   */
+  island(enabled = true) {
+    this.element._island = enabled;
+    this._getOrSetId();
+    if (enabled) {
+      this.element.__file = this._getCallerFile(2); // Captures the component file path
+    }
+    return this;
+  }
+
+  /**
+   * On the server, captures the reference handler's name for ESM extraction.
+   * @param {Function} callback
+   * @returns {this}
+   */
+  ref(callback) {
+    if (typeof callback === "function") {
+      this.element._refs.push({
+        name: meta._name || callback.name || "anonymous",
+        path: meta._source || null, // The absolute path s
+        handler: callback,
+      });
+      // Ensure element has a stable ID if it has a ref
+      this._getOrSetId();
+    }
+    return this;
+  }
+
+  /**
+   * Generates or retrieves a stable, hash-based ID for metadata association.
+   * @protected
+   * @returns {string} The data-domo-id.
+   */
+  _getOrSetId() {
+    const existing = this.element._attr["data-domo-id"] || this.element._attr["id"];
+    if (existing) {
+      return existing;
+    }
+
+    // Simple stable hash based on tag and current metadata state
+    const hash = Math.random().toString(36).substring(2, 7);
+    const id = `d-${hash}`;
+    this.element._attr["data-domo-id"] = id;
+    return id;
+  }
+  /**
+   * Gets the file path of the caller in the stack trace.
+   * @param {number} depth - How many steps back to look (default 2: the caller of the caller)
+   */
+  _getCallerFile(depth = 2) {
+    const originalPrepare = Error.prepareStackTrace;
+    Error.prepareStackTrace = (_, stack) => stack;
+    const stack = new Error().stack;
+    Error.prepareStackTrace = originalPrepare;
+
+    if (!stack || !stack[depth]) return null;
+
+    const filename = stack[depth].getFileName();
+
+    // Clean up "file://" prefixes for Windows/ESM compatibility
+    if (filename && filename.startsWith("file://")) {
+      return fileURLToPath(filename);
+    }
+    return filename;
+  }
+  _getExternalPath(fn, currentFile) {
+    // If the function has no name and is very short, it's likely an inline arrow fn
+    // However, the most reliable way in Node is checking the stack
+    const caller = getCallerFile(3); // Adjust depth based on where this is called
+
+    // Logic: If we can't find a source, or the source is the same as the
+    // component currently being built, we treat it as "inline".
+    if (!caller || caller === currentFile) {
+      return null;
+    }
+
+    return caller;
+  }
+}
+
+export default BaseServer;

package/src/server/builder.server.js

@@ -0,0 +1,47 @@
+import ChildrenServer from "./children.server.js";
+
+/**
+ * @class BuilderServer
+ * @extends ChildrenServer
+ */
+class BuilderServer extends ChildrenServer {
+  /**
+   * Serializes the virtual element and its metadata into an HTML string.
+   * @returns {string}
+   */
+  build() {
+    const tag = this.element._tag;
+    const cls = this.element._cls.join(" ");
+
+    const toKebab = (s) => s.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+
+    const css = Object.entries(this.element._css)
+      .map(([k, v]) => `${toKebab(k)}:${v}`)
+      .join(";");
+
+    const attrs = Object.entries(this.element._attr).map(([k, v]) =>
+      v === true ? k : `${k}="${String(v).replace(/"/g, """)}"`,
+    );
+
+    const data = Object.entries(this.element._data).map(([k, v]) => `data-${k}="${String(v).replace(/"/g, """)}"`);
+
+    if (cls) attrs.push(`class="${cls}"`);
+    if (css) attrs.push(`style="${css}"`);
+
+    const attrStr = attrs.concat(data).join(" ");
+
+    const escapeHTML = (str) => String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+    const children = this.element._child
+      .map((c) => {
+        if (typeof c === "string" || typeof c === "number") return escapeHTML(c);
+        if (c && typeof c.build === "function") return c.build();
+        return "";
+      })
+      .join("");
+
+    return `<${tag}${attrStr ? " " + attrStr : ""}>${children}</${tag}>`;
+  }
+}
+
+export default BuilderServer;