@zyrab/domo 1.3.0 → 1.5.0

package/src/server/children.server.js

@@ -0,0 +1,67 @@
+import EventsServer from "./events.server.js";
+
+/**
+ * @class ChildrenServer
+ * @extends EventsServer
+ */
+class ChildrenServer extends EventsServer {
+  child(children = []) {
+    const flattenedChildren = Array.isArray(children) ? children.flat() : [children];
+    flattenedChildren.forEach((child) => {
+      // Store reference. If it's a Domo instance, the Builder will call .build() on it later.
+      this.element._child.push(child);
+    });
+    return this;
+  }
+
+  append(children = []) {
+    return this.child(children);
+  }
+
+  appendTo(target) {
+    const targetEl = target && target._isDomo ? target.element : target;
+    if (targetEl && Array.isArray(targetEl._child)) {
+      targetEl._child.push(this);
+    }
+    return this;
+  }
+
+  parent(target) {
+    return this.appendTo(target);
+  }
+
+  clear() {
+    this.element._child = [];
+    return this;
+  }
+
+  replace(child, newChild) {
+    const idx = this.element._child.indexOf(child);
+    if (idx !== -1) {
+      this.element._child[idx] = newChild;
+    }
+    return this;
+  }
+
+  show(visible = true) {
+    if (!visible) {
+      this.element._attr["hidden"] = true;
+      this.element._css["display"] = "none";
+    } else {
+      delete this.element._attr["hidden"];
+      delete this.element._css["display"];
+    }
+    return this;
+  }
+
+  if(condition) {
+    if (!condition) {
+      return new this.constructor("if")
+        .attr({ hidden: true })
+        .data({ if: this.element._tag.toLowerCase() });
+    }
+    return this;
+  }
+}
+
+export default ChildrenServer;

package/src/server/classes.server.js

@@ -0,0 +1,42 @@
+import PropertiesServer from "./properties.server.js";
+
+/**
+ * @class ClassesServer
+ * @extends PropertiesServer
+ */
+class ClassesServer extends PropertiesServer {
+  /**
+   * 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._cls.push(...clsList);
+    return this;
+  }
+
+  rmvCls(classes) {
+    if (classes) {
+      const clsList = this._parseClassList(classes);
+      this.element._cls = this.element._cls.filter((c) => !clsList.includes(c));
+    }
+    return this;
+  }
+
+  tgglCls(className, force) {
+    const active = typeof force === "boolean" ? force : !this.element._cls.includes(className);
+    if (active) {
+      if (!this.element._cls.includes(className)) this.element._cls.push(className);
+    } else {
+      this.element._cls = this.element._cls.filter((c) => c !== className);
+    }
+    return this;
+  }
+}
+
+export default ClassesServer;

package/src/server/domo.server.js

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

package/src/server/events.server.js

@@ -0,0 +1,79 @@
+import ClassesServer from "./classes.server.js";
+
+/**
+ * @class EventsServer
+ * @extends ClassesServer
+ */
+class EventsServer extends ClassesServer {
+  /**
+   * Captures event metadata for the SSG.
+   * @param {string|object} eventMapOrName
+   * @param {Function} [callback]
+   * @param {object} [meta={}] - Injected by plugin: { _source, _name, ssg: boolean }
+   */
+  on(eventMapOrName, callback, meta = {}) {
+    // If user passed options (meta), check if ssg is explicitly disabled
+    if (meta.ssg === false) return this;
+
+    const id = this._getOrSetId();
+
+    if (typeof eventMapOrName === "object" && eventMapOrName !== null) {
+      // In object mode: .on({ click: fn }, { _source: '...', _name: '...' })
+      // callback actually acts as the 'meta' argument here
+      const metadata = callback || {};
+      for (const [event, value] of Object.entries(eventMapOrName)) {
+        const handler = Array.isArray(value) ? value[0] : value;
+        this._pushEvent(id, "direct", event, handler, null, metadata);
+      }
+    } else if (typeof callback === "function") {
+      // In single mode: .on('click', fn, { _source: '...', _name: '...' })
+      this._pushEvent(id, "direct", eventMapOrName, callback, null, meta);
+    }
+    return this;
+  }
+
+  onClosest(event, selectors = {}, meta = {}) {
+    if (meta.ssg === false) return this;
+    const id = this._getOrSetId();
+    for (const [selector, handler] of Object.entries(selectors)) {
+      this._pushEvent(id, "closest", event, handler, selector, meta);
+    }
+    return this;
+  }
+
+  onMatch(event, selectors = {}, meta = {}) {
+    if (meta.ssg === false) return this;
+    const id = this._getOrSetId();
+    for (const [selector, handler] of Object.entries(selectors)) {
+      this._pushEvent(id, "match", event, handler, selector, meta);
+    }
+    return this;
+  }
+
+  /**
+   * Internal helper to push event metadata.
+   * @private
+   */
+  _pushEvent(id, type, event, handler, selector = null, meta = {}) {
+    const evArr = (this.element._events ??= []);
+    let existing = evArr.find((e) => e.id === id && e.event === event);
+
+    if (!existing) {
+      existing = { id, event, handlers: [] };
+      evArr.push(existing);
+    }
+
+    // Capture path and name from the 'meta' object stamped by the plugin
+    existing.handlers.push({
+      type,
+      name: meta._name || handler.name || "anonymous",
+      handler,
+      path: meta._source || null, // STAMPED PATH
+      ...(selector && { selector }),
+    });
+
+    // Tag as island so SSG knows to include domo.client.js
+  }
+}
+
+export default EventsServer;

package/src/server/properties.server.js

@@ -0,0 +1,81 @@
+import BaseServer from "./base.server.js";
+
+/**
+ * @class PropertiesServer
+ * @extends BaseServer
+ */
+class PropertiesServer extends BaseServer {
+  /**
+   * Sets a metadata property.
+   * @protected
+   * @param {string} key
+   * @param {*} val
+   * @param {string} [type="_attr"]
+   * @returns {this}
+   */
+  _set(key, val, type = "_attr") {
+    if (val === undefined) return this;
+    if (type === "txt") {
+      this.element._child.push(String(val));
+    } else {
+      this.element[type][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, "txt");
+  }
+
+  attr(attributes = {}) {
+    for (const [key, value] of Object.entries(attributes)) {
+      this.element._attr[key] = value;
+    }
+    return this;
+  }
+
+  tgglAttr(attrName, force) {
+    if (typeof force === "boolean") {
+      if (force) this.element._attr[attrName] = true;
+      else delete this.element._attr[attrName];
+    } else {
+      if (this.element._attr[attrName]) delete this.element._attr[attrName];
+      else this.element._attr[attrName] = true;
+    }
+    return this;
+  }
+
+  data(data = {}) {
+    Object.entries(data).forEach(([key, val]) => {
+      this.element._data[key] = val;
+    });
+    return this;
+  }
+
+  css(styles = {}) {
+    Object.assign(this.element._css, styles);
+    return this;
+  }
+
+  /**
+   * Serializes state object into data-domo-state attribute.
+   * @param {object} obj
+   * @returns {this}
+   */
+  state(state = {}) {
+    Object.entries(state).forEach(([key, val]) => {
+      this.element._state[key] = val;
+    });
+    return this;
+  }
+}
+
+export default PropertiesServer;

package/src/base.js

@@ -1,80 +0,0 @@
-// 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

@@ -1,46 +0,0 @@
-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 escapeHTML = (str) => String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-
-    const attrStr = attrs.concat(data).join(" ");
-    const children = this.element._child
-      .map((c) => (typeof c === "string" ? escapeHTML(c) : c.build?.() || ""))
-      .join("");
-
-    return `<${tag}${attrStr ? " " + attrStr : ""}>${children}</${tag}>`;
-  }
-}
-
-export default Builder;

package/src/children.js

@@ -1,184 +0,0 @@
-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) {
-    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

@@ -1,62 +0,0 @@
-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;