@zyrab/domo 1.1.1 → 1.2.1

package/package.json

@@ -1,36 +1,39 @@
-{
-  "name": "@zyrab/domo",
-  "version": "1.1.1",
-  "description": "Minimalist DOM builder and chaining-friendly micro-framework with router support.",
-  "main": "index.js",
-  "type": "module",
-  "exports": {
-    ".": "./index.js"
-  },
-  "files": [
-    "index.js",
-    "src/"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zyrab/domo.git"
-  },
-  "keywords": [
-    "dom",
-    "builder",
-    "declarative",
-    "chaining",
-    "vanilla-js",
-    "router",
-    "components",
-    "event-delegation",
-    "zyrab"
-  ],
-  "author": "Zyrab",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/zyrab/domo/issues"
-  },
-  "homepage": "https://github.com/zyrab/domo#readme",
-  "logo": "https://github.com/zyrab/domo/blob/main/assets/logo.png"
-}
+{
+  "name": "@zyrab/domo",
+  "version": "1.2.1",
+  "description": "Minimalist DOM builder and chaining-friendly micro-framework with router support.",
+  "main": "./src/domo.js",
+  "type": "module",
+  "exports": {
+    "import": "./src/domo.js",
+    "default": "./src/domo.js"
+  },
+  "author": "Zyrab",
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "dom",
+    "builder",
+    "declarative",
+    "chaining",
+    "vanilla-js",
+    "router",
+    "components",
+    "event-delegation",
+    "zyrab"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zyrab/domo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zyrab/domo/issues"
+  },
+  "homepage": "https://github.com/zyrab/domo#readme",
+  "logo": "https://github.com/zyrab/domo/blob/main/assets/logo.png",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/base.js

@@ -0,0 +1,80 @@
+// Base.js
+const isServer = typeof document === "undefined";
+
+/**
+ * @class Base
+ * @description The foundational class for creating and managing DOM or virtual elements.
+ * Handles the basic setup and provides access to the underlying element.
+ */
+class Base {
+  /**
+   * @private
+   * @property {boolean} _virtual - True if running in a server-side (virtual DOM) environment.
+   */
+  _virtual;
+
+  /**
+   * @property {HTMLElement|object} element - The actual DOM element or its virtual representation.
+   */
+  element;
+
+  /**
+   * Creates an instance of Base.
+   * @param {string} [el="div"] - The HTML tag name for the element to create (e.g., 'div', 'span', 'button').
+   */
+  constructor(el = "div") {
+    this._virtual = isServer;
+    this.element = this._virtual ? this._vel(el) : this.el(el);
+  }
+
+  /**
+   * Creates a real HTML DOM element.
+   * @param {string} el - The HTML tag name (e.g., 'div', 'p').
+   * @returns {HTMLElement} The created DOM element.
+   * @example
+   * // Internally used:
+   * // this.el('div'); // Creates a <div> element
+   */
+  el(el) {
+    return document.createElement(String(el || "div").toLowerCase());
+  }
+
+  /**
+   * Creates a simple JavaScript object representing a virtual element for server-side rendering.
+   * @private
+   * @param {string} el - The HTML tag name.
+   * @returns {object} A plain object structure representing the virtual element.
+   * @example
+   * // Internally used for server-side:
+   * // this._vel('div'); // Returns { _tag: 'div', _cls: [], ... }
+   */
+  _vel(el) {
+    return {
+      _tag: el,
+      _cls: [],
+      _data: {},
+      _attr: {},
+      _css: {},
+      _child: [],
+      _events: [],
+    };
+  }
+
+  /**
+   * In browser context, passes the actual DOM element to the callback.
+   *
+   * @param {function(HTMLElement|string): void} callback -
+   *        Receives  the actual DOM element (in browser).
+   *
+   * @returns {this} The current Domo instance for chaining.
+
+  **/
+  ref(callback) {
+    if (this._virtual) return this;
+    if (typeof callback === "function") callback(this.element);
+
+    return this;
+  }
+}
+
+export default Base;

package/src/builder.js

@@ -0,0 +1,43 @@
+class Builder {
+  /**
+   * Builds and returns the final DOM element or its HTML string representation.
+   * If running in a browser environment, it returns the actual HTML element.
+   * If running in a server-side (virtual DOM) environment, it generates an HTML string.
+   * @returns {HTMLElement|string} The constructed DOM element or an HTML string.
+   * @example
+   * // In a browser:
+   * const myDiv = Domo('div').txt('Hello').build();
+   * document.body.appendChild(myDiv); // myDiv is an actual <div> element
+   *
+   * @example
+   * // In a server-side environment:
+   * // const htmlString = Domo('p').txt('Server-rendered content').build();
+   * // console.log(htmlString); // Outputs: "<p>Server-rendered content</p>"
+   */
+  build() {
+    if (!this._virtual) return this.element; // If not virtual, return the actual DOM element
+
+    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, "&quot;")}"`
+    );
+
+    const data = Object.entries(this.element._data).map(([k, v]) => `data-${k}="${String(v).replace(/"/g, "&quot;")}"`);
+
+    if (cls) attrs.push(`class="${cls}"`);
+    if (css) attrs.push(`style="${css}"`);
+
+    const attrStr = attrs.concat(data).join(" ");
+    const children = this.element._child.map((c) => (typeof c === "string" ? c : c.build?.() || "")).join("");
+
+    return `<${tag}${attrStr ? " " + attrStr : ""}>${children}</${tag}>`;
+  }
+}
+
+export default Builder;

package/src/children.js

@@ -0,0 +1,188 @@
+import { DomoClass } from "./domo.js";
+
+class Children {
+  /**
+   * Internally handles various types of input to ensure they become valid DOM Nodes
+   * or a string representation for virtual DOM.
+   * @private
+   * @param {*} element - The input to process (Domo instance, Node, string, number).
+   * @returns {Node|string|Domo} A DOM Node (HTMLElement, TextNode, DocumentFragment),
+   * a string for virtual children, or a Domo instance for virtual children.
+   */
+  _handleElementInstance(element) {
+    // Check if Domo class exists (it's imported in main.domo.js for final class)
+    // To avoid circular dependency in JSDoc parsing, we'll check runtime type.
+    // For JSDoc type checking, we assume Domo is available in the context of main.domo.js.
+    // @ts-ignore - Ignore potential 'Domo is not defined' for JSDoc tool
+    if (element instanceof DomoClass) return element.build();
+
+    if (element instanceof DocumentFragment) return element;
+    if (element instanceof Node) return element;
+    if (typeof element === "string" || typeof element === "number") {
+      return document.createTextNode(element); // Convert strings/numbers to text nodes
+    }
+    return document.createTextNode(`⚠ Invalid child: ${String(element)}`); // Fallback for invalid input
+  }
+
+  /**
+   * Appends one or more children to the element.
+   * This method accepts a wide range of child types, including other Domo instances,
+   * native DOM nodes, DocumentFragments, and simple text/numbers, even in nested arrays.
+   * @param {(Node|string|number|Domo|DocumentFragment|Array<any>)[]} [children=[]] - An array of children to append. Can contain mixed types and nested arrays.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('div').child([
+   * Domo('span').txt('Hello'),
+   * document.createElement('br'),
+   * 'World!',
+   * [Domo('em').txt('Nested')]
+   * ]);
+   */
+  child(children = []) {
+    const flattenedChildren = children.flat(); // Handle nested arrays of children
+    flattenedChildren.forEach((child) => {
+      if (this._virtual) {
+        // In virtual mode, store Domo instances or their string representation
+        // @ts-ignore - Ignore potential 'Domo is not defined' for JSDoc tool
+        this.element._child.push(child instanceof DomoClass ? child : String(child));
+      } else this.element.appendChild(this._handleElementInstance(child));
+    });
+    return this;
+  }
+
+  /**
+   * Appends one or more children to the element.
+   * This is an alias for the `child` method, offering a more common naming convention.
+   * @param {(Node|string|number|Domo|DocumentFragment|Array<any>)[]} [children=[]] - An array of children to append. Can contain mixed types and nested arrays.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('ul').append([
+   * Domo('li').txt('Item 1'),
+   * Domo('li').txt('Item 2')
+   * ]);
+   */
+  append(children = []) {
+    return this.child(children);
+  }
+
+  /**
+   * Appends the current Domo element to a specified target element in the DOM.
+   * @param {HTMLElement|Domo|DocumentFragment} target - The element to which the current Domo element will be appended. Can be a native HTMLElement, another Domo instance, or a DocumentFragment.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * const myDiv = Domo('div').txt('My Content');
+   * myDiv.appendTo(document.body); // Appends the div to the body
+   *
+   * const container = Domo('main');
+   * myDiv.appendTo(container); // Appends to another Domo instance
+   */
+  appendTo(target) {
+    // @ts-ignore - Ignore potential 'Domo is not defined' for JSDoc tool
+    const targetNode = target instanceof DomoClass ? target.element : target; // Get native element if Domo instance
+    if (targetNode instanceof Node) {
+      // Ensure it's a DOM Node
+      targetNode.appendChild(this.element);
+    }
+    return this;
+  }
+
+  /**
+   * Appends the current Domo element to a specified target parent.
+   * This is an alias for the `appendTo` method.
+   * @param {HTMLElement|Domo|DocumentFragment} target - The parent element to which the current Domo element will be appended.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('img').attr({ src: 'image.jpg' }).parent(document.getElementById('image-gallery'));
+   */
+  parent(target) {
+    return this.appendTo(target);
+  }
+
+  /**
+   * Removes all child nodes from the element, effectively emptying its content.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('ul').child([Domo('li'), Domo('li')]).clear(); // Removes both <li>s
+   */
+  clear() {
+    this.element.replaceChildren();
+    return this;
+  }
+
+  /**
+   * Replaces an existing child element with a new one, or replaces the Domo element itself if it's the target.
+   * @param {Node} child - The old child element (or the Domo element itself) to be replaced.
+   * @param {(Node|string|number|Domo|DocumentFragment|Array<any>)} newChild - The new element (or content) to insert. Can be a Domo instance, native Node, string, or number.
+   * @returns {this} The current Domo instance for chaining (or the new Domo instance if the original element was replaced).
+   * @example
+   * const oldParagraph = document.getElementById('old-p');
+   * const newDiv = Domo('div').txt('New Content');
+   * Domo('body').replace(oldParagraph, newDiv);
+   *
+   * // To replace the Domo element itself:
+   * // const myButton = Domo('button').id('myBtn');
+   * // myButton.replace(myButton.element, Domo('a').txt('Link'));
+   */
+  replace(child, newChild) {
+    const resolvedNew = this._handleElementInstance(newChild);
+    const resolvedOld = child; // Child is expected to be a Node already based on context
+
+    if (resolvedOld === this.element) {
+      this.element.replaceWith(resolvedNew);
+      this.element = resolvedNew; // Update the internal reference to the new element
+    } else if (this.element.contains(resolvedOld)) {
+      resolvedOld.replaceWith(resolvedNew);
+    }
+
+    return this;
+  }
+
+  /**
+   * Shows or hides the element by controlling its CSS `display` property.
+   * @param {boolean} [visible=true] - If `true`, the element is shown. If `false`, it's hidden.
+   * @param {string} [displayValue='block'] - The CSS `display` value to use when showing the element (e.g., 'block', 'flex', 'inline-block').
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('div').show(false); // Hides the div
+   * Domo('span').show(true, 'inline'); // Shows the span as inline
+   */
+  show(visible = true, displayValue = "block") {
+    this.element.style.display = visible ? displayValue : "none";
+    return this;
+  }
+
+  /**
+   * Conditionally returns the current Domo instance or a hidden placeholder element.
+   * This allows for conditional rendering based on a boolean condition. If the condition is false,
+   * a hidden 'if' element is returned, ensuring method chaining can continue without rendering
+   * the actual element.
+   * @param {boolean} condition - The condition to evaluate.
+   * @returns {this|Domo} The current Domo instance if the condition is true,
+   * or a new hidden Domo instance representing the 'if' placeholder if false.
+   * @example
+   * const dataExists = true;
+   * Domo('div')
+   * .if(dataExists)
+   * .txt('Data is here!'); // This will render
+   *
+   * const userIsAdmin = false;
+   * Domo('button')
+   * .if(userIsAdmin)
+   * .txt('Admin Panel'); // This button will not be rendered (a hidden placeholder is returned)
+   */
+  if(condition) {
+    // @ts-ignore - Ignore potential 'Domo is not defined' for JSDoc tool
+    if (!condition) {
+      return new DomoClass("if")
+        .attr({
+          hidden: true,
+        })
+        .data({
+          if: !this._virtual ? this.element.tagName.toLowerCase() : this.element._tag.toLowerCase(),
+        });
+    }
+    return this;
+  }
+}
+
+export default Children;

package/src/classes.js

@@ -0,0 +1,62 @@
+class Classes {
+  /**
+   * Normalizes various inputs into a clean array of class names.
+   * Handles strings (space-separated) and arrays of strings.
+   * @private
+   * @param {string|string[]} input - A string of space-separated class names, or an array of class names.
+   * @returns {string[]} An array of cleaned class names.
+   */
+  _parseClassList(input) {
+    return Array.isArray(input) ? input.filter(Boolean) : String(input).split(" ").filter(Boolean);
+  }
+
+  /**
+   * Adds one or more CSS classes to the element.
+   * @param {string|string[]} classes - A single class name, a string of space-separated class names, or an array of class names.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('div').cls('active highlight');
+   * Domo('button').cls(['btn', 'btn-primary']);
+   */
+  cls(classes) {
+    if (!classes) return this;
+    const clsList = this._parseClassList(classes);
+    if (this._virtual) this.element._cls.push(...clsList);
+    else this.element.classList.add(...clsList);
+    return this;
+  }
+
+  /**
+   * Removes one or more CSS classes from the element.
+   * @param {string|string[]} classes - A single class name, a string of space-separated class names, or an array of class names.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('div').rmvCls('active');
+   * Domo('p').rmvCls(['old-style', 'unused']);
+   */
+  rmvCls(classes) {
+    if (classes) {
+      this.element.classList.remove(...this._parseClassList(classes));
+    }
+    return this;
+  }
+
+  /**
+   * Toggles a single CSS class on or off for the element.
+   * @param {string} className - The class name to toggle.
+   * @param {boolean} [force] - If `true`, the class is added. If `false`, it's removed.
+   * If omitted, the class's presence is flipped.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * // Toggle 'active' class:
+   * Domo('button').tgglCls('active');
+   * // Force add 'highlight' class:
+   * Domo('div').tgglCls('highlight', true);
+   */
+  tgglCls(className, force) {
+    this.element.classList.toggle(className, force);
+    return this;
+  }
+}
+
+export default Classes;

package/src/domo.js

@@ -0,0 +1,77 @@
+import Base from "./base.js";
+import Properties from "./properties.js";
+import Classes from "./classes.js";
+import Events from "./events.js";
+import Children from "./children.js";
+import Builder from "./builder.js";
+
+/**
+ * @class Domo
+ * @augments Base
+ * @description The main class for creating and manipulating DOM elements,
+ * combining functionalities from various modules (Properties, Classes, Events, Children, Builder).
+ * This class provides a fluent, chainable API for building and interacting with HTML elements.
+ */
+class DomoClass extends Base {
+  // Ensure the constructor explicitly calls the parent's constructor.
+  // This makes sure `this._virtual` and `this.element` are initialized by Base.
+  constructor(el = "div") {
+    super(el); // Calls Base's constructor
+  }
+}
+
+// Apply all mixin methods to the Domo prototype
+// These lines integrate the methods from other classes into the Domo class's prototype,
+// making them available on any Domo instance.
+Object.getOwnPropertyNames(Properties.prototype)
+  .filter((p) => p !== "constructor")
+  .forEach((name) => {
+    DomoClass.prototype[name] = Properties.prototype[name];
+  });
+Object.getOwnPropertyNames(Classes.prototype)
+  .filter((p) => p !== "constructor")
+  .forEach((name) => {
+    DomoClass.prototype[name] = Classes.prototype[name];
+  });
+Object.getOwnPropertyNames(Events.prototype)
+  .filter((p) => p !== "constructor")
+  .forEach((name) => {
+    DomoClass.prototype[name] = Events.prototype[name];
+  });
+Object.getOwnPropertyNames(Children.prototype)
+  .filter((p) => p !== "constructor")
+  .forEach((name) => {
+    DomoClass.prototype[name] = Children.prototype[name];
+  });
+Object.getOwnPropertyNames(Builder.prototype)
+  .filter((p) => p !== "constructor")
+  .forEach((name) => {
+    DomoClass.prototype[name] = Builder.prototype[name];
+  });
+
+/**
+ * A factory function to create a new Domo element instance.
+ * This is the primary way to start building an element, avoiding the need for the `new` keyword.
+ * @param {string} [el="div"] - The HTML tag name for the element to create (e.g., 'div', 'span', 'button').
+ * @returns {Domo} A new Domo instance, ready for method chaining.
+ * @example
+ * // Create a div and add text and a class:
+ * const myDiv = Domo('div').txt('Hello World').cls('container');
+ *
+ * // Create a button and attach an event:
+ * const myButton = Domo('button')
+ * .txt('Click Me')
+ * .on('click', () => alert('Button clicked!'));
+ *
+ * // Append to the document body:
+ * myButton.appendTo(document.body);
+ */
+function Domo(el = "div") {
+  return new DomoClass(el);
+}
+
+// Export the factory function as the default export
+export default Domo;
+
+// Export the Domo Class itself
+export { DomoClass };