@zyrab/domo 1.0.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,137 @@
+# Domo
+
+![Domo Logo](./assets/logo.png)
+
+**Domo** is a tiny fluent helper for creating and working with DOM elements.  
+It simplifies native APIs with a chainable, intuitive interface.
+
+Originally built for personal use, it's growing into a lightweight UI toolkit with a router, planned components, and scoped styles.  
+No dependencies. No build step. Just clean, direct DOM manipulation.
+
+---
+
+## Features
+
+- Fluent, chainable DOM API
+- Set ID, text, value, class, style, data, attributes
+- Conditional rendering with `.if()` and `.show()`
+- Event handling: `.on`, `.onClosest`, `.onMatch`
+- Simple DOM ops: `.append`, `.clear`, `.replace`
+- Built-in router:
+  - History API, nested/dynamic routes
+  - Scroll and metadata handling
+  - Route info and listeners
+
+---
+
+## Installation
+
+```bash
+npm install @zyrab/domo
+```
+
+---
+
+## Usage
+
+```js
+import Domo from " @zyrab/domo";
+
+const btn = Domo("button")
+  .id("submit-btn")
+  .cls(["btn", "primary"])
+  .txt("Submit")
+  .on("click", () => alert("Submitted!"))
+  .build();
+
+document.body.appendChild(btn);
+```
+
+---
+
+## Router
+
+The built-in router enables history-based navigation with a simple nested config structure.
+
+```js
+import { Router } from "@zyrab/domo";
+
+Router.routes({
+  "/": { component: Home, meta: { title: "Home" } },
+  "/about": { component: About, meta: { title: "About" } },
+  "/blog": {
+    children: {
+      "/": { component: Blog, meta: { title: "Blog" } },
+      "/:slug": { component: BlogPost, meta: { title: "Post" } },
+    },
+  },
+  "*": { component: Error, meta: { title: "404" } },
+});
+
+document.body.appendChild(Router.mount());
+Router.init();
+
+Router.goTo("/about");
+
+Router.back();
+
+Router.listen(({ meta, params }) => {
+  console.log("Route changed:", meta.title, params);
+});
+
+const { meta, params, segments } = Router.info();
+```
+
+---
+
+## Planned
+
+- DOM-based components
+- Custom scoped style system
+- Prebuilt reusable elements
+- Examples folder with real use cases
+
+---
+
+## API Reference
+
+- Domo(tag = "div") — Creates a DOM element
+- .id(string)
+- .val(string)
+- .txt(string)
+- .cls(string | string[])
+- .rmvCls(string | string[])
+- .tgglCls(string, force?)
+- .attr(object)
+- .tgglAttr(name, force?)
+- .data(object)
+- .css(styles)
+- .on(event, callback)
+- .onMatch(event, { selector: callback })
+- .onClosest(event, { selector: callback })
+- .child([children])
+- .clear()
+- .replace(child, newChild)
+- .show(bool, display?)
+- .if(condition)
+- .ref(callback) — Callback access to raw element
+- .build() — Returns the constructed HTMLElement
+
+Full reference:
+[Domo](docs/Domo.md)
+[Router](docs/Router.md)
+
+---
+
+## Contributing
+
+Suggestions, fixes, or features are welcome.
+This is a small project made for personal use — but if you see something worth improving, feel free to help.
+
+→ [Read the Contributing Guide](CONTRIBUTING)
+
+---
+
+## License
+
+[MIT License](LICENSE)

package/index.js

@@ -0,0 +1,4 @@
+import Domo from "./src/core/Domo.js";
+import Router from "./src/core/Router.js";
+
+export { Domo, Router };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@zyrab/domo",
+  "version": "1.0.0",
+  "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": "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"
+}

package/src/core/Domo.js

@@ -0,0 +1,290 @@
+/**
+ * Domo - Lightweight helper class for creating and manipulating DOM elements fluently.
+ */
+class Domo {
+  /**
+   * @param {string} [el='div'] - The tag name of the element to create.
+   */
+  constructor(el = "div") {
+    this.element = this.el(el);
+  }
+
+  /**
+   * Creates a DOM element.
+   * @param {string} el - Element tag name.
+   * @returns {HTMLElement}
+   */
+  el(el) {
+    return document.createElement(String(el || "div").toLowerCase());
+  }
+
+  /**
+   * Provides direct reference to the created element.
+   * @param {(el: HTMLElement) => void} callBack
+   * @returns {Domo}
+   */
+  ref(callBack) {
+    if (typeof callBack === "function") callBack(this.element);
+    return this;
+  }
+
+  /**
+   * Sets a property on the element if the value is not undefined.
+   * @private
+   * @param {string} key
+   * @param {*} val
+   * @returns {Domo}
+   */
+  _set(key, val) {
+    if (val !== undefined) this.element[key] = val;
+    return this;
+  }
+
+  /** @param {string} id */
+  id(id) {
+    return this._set("id", id);
+  }
+
+  /** @param {string} value */
+  val(value) {
+    return this._set("value", value);
+  }
+
+  /** @param {string} text */
+  txt(text) {
+    return this._set("textContent", text);
+  }
+
+  /**
+   * Normalizes a class list input.
+   * @private
+   * @param {string|string[]} input
+   * @returns {string[]}
+   */
+  _parseClassList(input) {
+    return Array.isArray(input)
+      ? input.filter(Boolean)
+      : String(input).split(" ").filter(Boolean);
+  }
+
+  /**
+   * Adds classes
+   *  @param {string|string[]} classes
+   */
+  cls(classes) {
+    if (classes) {
+      this.element.classList.add(...this._parseClassList(classes));
+    }
+    return this;
+  }
+
+  /**
+   * Removes classes
+   *   @param {string|string[]} classes
+   */
+  rmvCls(classes) {
+    if (classes) {
+      this.element.classList.remove(...this._parseClassList(classes));
+    }
+    return this;
+  }
+
+  /**
+   * Toggles a class.
+   * @param {string} className
+   * @param {boolean} [force]
+   */
+  tgglCls(className, force) {
+    this.element.classList.toggle(className, force);
+    return this;
+  }
+
+  /**
+   * Sets attributes (skips event attributes).
+   * @param {Record<string, any>} attributes
+   */
+  attr(attributes = {}) {
+    Object.entries(attributes).forEach(([key, value]) => {
+      if (key.startsWith("on")) return;
+      if (typeof value === "boolean") {
+        if (value) this.element.setAttribute(key, "");
+        else this.element.removeAttribute(key);
+      } else if (value != null) {
+        this.element.setAttribute(key, value);
+      }
+    });
+    return this;
+  }
+
+  /**
+   * Toggles an attribute.
+   * @param {string} attrName
+   * @param {boolean} [force]
+   */
+  tgglAttr(attrName, force) {
+    if (attrName.startsWith("on")) return;
+    if (typeof force === "boolean") {
+      if (force) {
+        this.element.setAttribute(attrName, "");
+      } else {
+        this.element.removeAttribute(attrName);
+      }
+    } else {
+      if (this.element.hasAttribute(attrName)) {
+        this.element.removeAttribute(attrName);
+      } else {
+        this.element.setAttribute(attrName, "");
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Sets data-* attributes.
+   * @param {Record<string, string>} data
+   */
+  data(data = {}) {
+    Object.entries(data).forEach(([key, val]) => {
+      this.element.dataset[key] = val;
+    });
+    return this;
+  }
+
+  /**
+   * Sets CSS styles.
+   * @param {Partial<CSSStyleDeclaration>} styles
+   */
+  css(styles = {}) {
+    Object.assign(this.element.style, styles);
+    return this;
+  }
+
+  /**
+   * Adds an event listener.
+   * @param {string} event
+   * @param {EventListenerOrEventListenerObject} callback
+   * @param {AddEventListenerOptions} [options]
+   */
+  on(event, callback, options = {}) {
+    this.element.addEventListener(event, callback, options);
+    return this;
+  }
+
+  /** @private */
+  _handleClosest(e, map) {
+    for (const [selector, handler] of Object.entries(map)) {
+      const match = e.target.closest(selector);
+      if (match) handler(e, match);
+    }
+  }
+
+  /**
+   * Delegates events to closest matching ancestor.
+   * @param {string} event
+   * @param {Record<string, (e: Event, target: Element) => void>} selectors
+   * @param {AddEventListenerOptions} [options]
+   */
+  onClosest(event, selectors = {}, options = {}) {
+    return this.on(event, (e) => this._handleClosest(e, selectors), options);
+  }
+
+  /** @private */
+  _handleMatches(e, map) {
+    for (const [selector, handler] of Object.entries(map)) {
+      if (e.target.matches(selector)) handler(e, e.target);
+    }
+  }
+
+  /**
+   * Delegates events using element.matches.
+   * @param {string} event
+   * @param {Record<string, (e: Event, target: Element) => void>} selectors
+   * @param {AddEventListenerOptions} [options]
+   */
+  onMatch(event, selectors = {}, options = {}) {
+    return this.on(event, (e) => this._handleMatches(e, selectors), options);
+  }
+
+  /** @private */
+  _handleElementInstance(element) {
+    if (element instanceof Domo) 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);
+    }
+    return document.createTextNode(`⚠ Invalid child: ${String(element)}`);
+  }
+
+  /**
+   * Appends children (can be nested arrays, strings, numbers, fragments, elements).
+   * @param {any[]} children
+   */
+  child(children = []) {
+    const flattenedChildren = children.flat();
+    flattenedChildren.forEach((child) => {
+      this.element.appendChild(this._handleElementInstance(child));
+    });
+    return this;
+  }
+
+  /**
+   * Removes all children.
+   */
+  clear() {
+    this.element.replaceChildren();
+    return this;
+  }
+
+  /**
+   * Replaces a child element or self with a new one.
+   * @param {Node} child
+   * @param {any} newChild
+   */
+  replace(child, newChild) {
+    const instance = this._handleElementInstance(newChild);
+
+    if (child === this.element) {
+      this.element.replaceWith(instance);
+      this.element = instance;
+    } else if (this.element.contains(child)) {
+      child.replaceWith(instance);
+    }
+
+    return this;
+  }
+
+  /**
+   * Shows or hides the element.
+   * @param {boolean} [visible=true]
+   * @param {string} [displayValue='block']
+   */
+  show(visible = true, displayValue = "block") {
+    this.element.style.display = visible ? displayValue : "none";
+    return this;
+  }
+
+  /**
+   * Conditionally render element, or return dummy hidden placeholder.
+   * @param {boolean} condition
+   * @returns {Domo}
+   */
+  if(condition) {
+    if (!condition) {
+      return new Domo("if")
+        .attr({ hidden: true })
+        .data({ if: this.element.tagName.toLowerCase() });
+    }
+    return this;
+  }
+
+  /**
+   * Returns the constructed DOM element.
+   * @returns {HTMLElement}
+   */
+  build() {
+    return this.element;
+  }
+}
+
+export default Domo;

package/src/core/DomoSVG.js

@@ -0,0 +1,63 @@
+class DomoSVG extends Domo {
+  constructor(tag = "svg") {
+    super(tag); // Call Domo constructor with tag
+    if (!this.isSVGTag(tag)) {
+      throw new Error(`Invalid SVG tag: ${tag}`);
+    }
+  }
+
+  /**
+   * Check if the tag is a valid SVG element.
+   * @param {string} tag
+   * @returns {boolean}
+   */
+  isSVGTag(tag) {
+    const svgTags = [
+      "svg",
+      "path",
+      "circle",
+      "rect",
+      "line",
+      "ellipse",
+      "polygon",
+      "g",
+      "text",
+      "use",
+      "defs",
+      "clipPath",
+      "marker",
+      "mask",
+      "style",
+      "linearGradient",
+      "radialGradient",
+      "stop",
+    ];
+    return svgTags.includes(tag);
+  }
+
+  /**
+   * Override the el method to handle SVG namespace creation.
+   * @param {string} tag
+   * @returns {HTMLElement}
+   */
+  el(tag) {
+    return this.isSVGTag(tag)
+      ? document.createElementNS("http://www.w3.org/2000/svg", tag)
+      : super.el(tag); // Fallback to regular DOM creation
+  }
+
+  /**
+   * Set attributes specific to SVG elements.
+   * @param {Record<string, any>} attributes
+   * @returns {DomoSVG}
+   */
+  attr(attributes = {}) {
+    Object.entries(attributes).forEach(([key, value]) => {
+      if (key.startsWith("on")) return;
+      if (value != null) {
+        this.element.setAttributeNS(null, key, value); // Set using SVG-specific namespace
+      }
+    });
+    return this;
+  }
+}

package/src/core/Router.js

@@ -0,0 +1,203 @@
+let _routes = {};
+let _listeners = [];
+const _scrollPositions = {};
+let _previousUrl = "";
+
+let _root = document.createElement("main");
+_root.id = "main";
+
+function init() {
+  ["DOMContentLoaded", "popstate"].forEach((event) =>
+    window.addEventListener(event, async () => {
+      saveScroll(_previousUrl);
+      const url = path();
+      load(url);
+      _previousUrl = url;
+      restoreScroll();
+    })
+  );
+}
+
+async function render({ component, meta }, params) {
+  try {
+    const content = await component(params);
+    _root.replaceChildren();
+
+    if (content instanceof HTMLElement) {
+      _root.appendChild(content);
+    } else if (typeof content === "string") {
+      const wrapper = document.createElement("div");
+      wrapper.textContent = content;
+      _root.appendChild(wrapper);
+    } else {
+      throw new Error("Unsupported component output type");
+    }
+    if (meta) {
+      document.title = meta?.title;
+      document
+        .querySelector("meta[name='description']")
+        .setAttribute("content", meta?.description);
+    }
+  } catch (error) {
+    console.error("Rendering error:", error);
+    const fallback = _routes["*"]?.component?.({ error: err.message });
+    if (fallback) {
+      _root.replaceChildren();
+      _root.appendChild(fallback);
+    }
+  }
+}
+async function goTo(path) {
+  saveScroll(_previousUrl);
+  await load(path);
+  _previousUrl = path;
+  restoreScroll();
+}
+
+const path = () => window.location.pathname + window.location.hash;
+
+function info() {
+  const { segments } = parseUrl(path());
+  const { routeData, params } = match(segments);
+  return { meta: routeData.meta || {}, params, segments };
+}
+
+function parseUrl(url) {
+  // Remove the hash from the URL
+  const pureUrl = url.includes("#") ? url.split("#")[0] : url;
+  // Split the URL into segments keepinig '/' for nested routes
+  const segments = pureUrl.split(/(?=\/)/g).filter(Boolean);
+  return {
+    segments,
+    pureUrl,
+  };
+}
+
+function match(segments) {
+  if (!segments.length) return { routeData: _routes["/"] || _routes["*"] };
+
+  let current = _routes;
+  let params = {};
+
+  for (const segment of segments) {
+    if (current[segment]) {
+      // exact match found go deeper
+      current = current[segment].children || current[segment];
+    } else {
+      // look for dynamic route
+      const dynamic = Object.keys(current).find((k) => k.includes(":"));
+      if (!dynamic) return { routeData: _routes["*"], params: {} };
+
+      const parmName = dynamic.split(":")[1];
+      params = { ...params, [parmName]: segment.split("/")[1] };
+      current = current[dynamic].children || current[dynamic];
+    }
+  }
+  // we send for rendering default child if component doesnt exists
+  const final = current.component ? current : current["/"] || _routes["*"];
+
+  return { params, routeData: final };
+}
+
+async function load(url) {
+  const { segments, pureUrl } = parseUrl(url);
+  const { routeData, params } = match(segments);
+
+  if (path() !== url) {
+    history.pushState(null, null, pureUrl);
+  }
+
+  if (url === _previousUrl) return;
+
+  await render(routeData, params);
+  if (_listeners.length > 0) notify(info());
+}
+
+function notify(info) {
+  _listeners.forEach((cb) => cb(info));
+}
+function saveScroll(path = window.location.pathname) {
+  _scrollPositions[path] = window.scrollY;
+}
+
+function restoreScroll() {
+  const pos = _scrollPositions[window.location.pathname];
+  window.scrollTo(0, pos || 0);
+}
+
+export const Router = {
+  /**
+   * Mount point of the router, where components will be rendered.
+   * @returns {HTMLElement} The root DOM element used by the router.
+   */
+  mount: () => _root,
+
+  /**
+   * Initializes the router by setting up event listeners and loading the initial route.
+   */
+  init,
+
+  /**
+   * Programmatically navigate to a new route.
+   * @param {string} path - The path to navigate to.
+   * @returns {Promise<void>}
+   */
+  goTo,
+
+  /**
+   * Navigate one step back in browser history.
+   */
+  back: () => history.back(),
+
+  /**
+   * Get the current full path including hash.
+   * @returns {string} The current path.
+   */
+  path,
+
+  /**
+   * Get the previous URL path.
+   * @returns {string}
+   */
+  prev: () => _previousUrl || "/",
+
+  /**
+   * Returns the base (first) segment of the current path.
+   * @returns {string}
+   */
+  base: () => parseUrl(path()).segments[0],
+
+  /**
+   * Returns info about the current route.
+   * @returns {{ meta: object, params: object, segments: string[] }}
+   */
+  info,
+
+  /**
+   * Define your route structure.
+   *
+   * @param {Object} config - Route config object. Supports nested and dynamic routes.
+   * @example
+   * Router.routes({
+   *   '/': { component: Home, meta: { title: "Home", description: "Welcome" } },
+   *   '/blog': {
+   *     children: {
+   *       '/:slug': { component: BlogPost },
+   *       '/': { component: Blog }
+   *     }
+   *   },
+   *   '*': { component: NotFound }
+   * });
+   */
+  routes: (config) => {
+    _routes = config;
+  },
+
+  /**
+   * Register a listener for route changes.
+   * @param {(info: ReturnType<typeof info>) => void} fn - Listener callback.
+   */
+  listen: (fn) => {
+    if (typeof fn === "function") _listeners.push(fn);
+  },
+};