@zyrab/domo 1.1.1 → 1.2.0

package/src/events.js

@@ -0,0 +1,165 @@
+class Events {
+  _pushVirtualHandler(id, event, entry) {
+    const evArr = (this.element._events ??= []);
+    const existing = evArr.find((e) => e.id === id && e.event === event);
+    if (existing) {
+      existing.handlers.push(entry);
+    } else {
+      evArr.push({ id, event, handlers: [entry] });
+    }
+  }
+
+  /**
+   * Adds one or multiple event listeners to the element.
+   *
+   * This method supports two main ways to add events:
+   * 1. A single event: `Domo(...).on('click', myClickHandler)`
+   * 2. Multiple events using an object: `Domo(...).on({ click: myClickHandler, mouseenter: [anotherHandler, { once: true }] })`
+   *
+   * @param {string | Record<string, Function | [Function, AddEventListenerOptions]>} eventMapOrName -
+   * Either the name of a single event (e.g., 'click'), or an object where keys are event names
+   * and values are event handler functions (or arrays containing the handler and options).
+   * @param {EventListenerOrEventListenerObject} [callback] - The function to call when the event occurs. Required if `eventMapOrName` is a string.
+   * @param {AddEventListenerOptions} [options={}] - An object specifying characteristics about the event listener (e.g., `{ once: true, capture: true }`). Required if `eventMapOrName` is a string.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * // Single event:
+   * Domo('button').on('click', () => console.log('Button clicked!'));
+   *
+   * @example
+   * // Multiple events with options:
+   * Domo('input').on({
+   * focus: () => console.log('Input focused'),
+   * blur: [() => console.log('Input blurred'), { once: true }]
+   * });
+   */
+
+  on(eventMapOrName, callback, options = {}) {
+    if (this._virtual && eventMapOrName !== null) {
+      if (options.ssg === false) return this;
+      const elId = this.element._attr?.id;
+      if (!elId) throw new Error(`[Domo.on] .id() must be called before .on(...) in SSG mode`);
+
+      if (typeof eventMapOrName === "object") {
+        for (const [event, value] of Object.entries(eventMapOrName)) {
+          const handler = Array.isArray(value) ? value[0] : value;
+          this._pushVirtualHandler(elId, event, { type: "direct", handler });
+        }
+      } else {
+        this._pushVirtualHandler(elId, eventMapOrName, { type: "direct", handler: callback });
+      }
+
+      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 {
+      this.element.addEventListener(eventMapOrName, callback, options);
+    }
+    return this;
+  }
+
+  /**
+   * Internal helper for `onClosest`. Finds the closest ancestor matching a selector and calls its handler.
+   * @private
+   * @param {Event} e - The native event object.
+   * @param {Record<string, (e: Event, target: Element) => void>} map - An object mapping CSS selectors to handler functions.
+   */
+  _handleClosest(e, map) {
+    for (const [selector, handler] of Object.entries(map)) {
+      const match = e.target.closest(selector);
+      if (match) handler(e, match);
+    }
+  }
+
+  /**
+   * Attaches an event listener that triggers when an event occurs on an element,
+   * but the handler is only called if the event target or its closest ancestor matches a given selector.
+   * This is useful for handling events on dynamically added elements or multiple elements with similar structure.
+   * @param {string} event - The name of the event to listen for (e.g., 'click', 'mouseover').
+   * @param {Record<string, (e: Event, target: Element) => void>} selectors - An object where keys are CSS selectors and values are handler functions.
+   * The handler receives the event object and the matching element (which could be the target or an ancestor).
+   * @param {AddEventListenerOptions} [options] - Options for `addEventListener`.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('ul').onClosest('click', {
+   * 'li.item': (e, li) => console.log('Clicked list item:', li.textContent),
+   * 'button.delete': (e, btn) => console.log('Delete button clicked for:', btn.closest('li').id)
+   * });
+   */
+  onClosest(event, selectors = {}, options = {}) {
+    if (this._virtual && event !== null) {
+      if (options.ssg === false) return this;
+      const elId = this.element._attr?.id;
+      if (!elId) throw new Error(`[Domo.onClosest] .id() must be called before .onClosest(...) in SSG mode`);
+
+      for (const [selector, handler] of Object.entries(selectors)) {
+        this._pushVirtualHandler(elId, event, {
+          type: "closest",
+          selector,
+          handler,
+        });
+      }
+
+      return this;
+    }
+
+    return this.on(event, (e) => this._handleClosest(e, selectors), options);
+  }
+
+  /**
+   * Internal helper for `onMatch`. Checks if the event target matches a selector and calls its handler.
+   * @private
+   * @param {Event} e - The native event object.
+   * @param {Record<string, (e: Event, target: Element) => void>} map - An object mapping CSS selectors to handler functions.
+   */
+  _handleMatches(e, map) {
+    for (const [selector, handler] of Object.entries(map)) {
+      if (e.target.matches(selector)) handler(e, e.target);
+    }
+  }
+
+  /**
+   * Attaches an event listener that triggers a handler only if the event's direct target element matches a specific CSS selector.
+   * This is useful for handling events on multiple elements where you only care about the exact element clicked.
+   * @param {string} event - The name of the event to listen for (e.g., 'click', 'keyup').
+   * @param {Record<string, (e: Event, target: Element) => void>} selectors - An object where keys are CSS selectors and values are handler functions.
+   * The handler receives the event object and the exact matching element.
+   * @param {AddEventListenerOptions} [options] - Options for `addEventListener`.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * // Only logs if a button with class 'action-btn' is *directly* clicked
+   * Domo('div').onMatch('click', {
+   * 'button.action-btn': (e, btn) => console.log('Action button clicked:', btn.textContent),
+   * 'input[type="checkbox"]': (e, checkbox) => console.log('Checkbox toggled:', checkbox.checked)
+   * });
+   */
+  onMatch(event, selectors = {}, options = {}) {
+    if (this._virtual && event !== null) {
+      if (options.ssg === false) return this;
+      const elId = this.element._attr?.id;
+      if (!elId) throw new Error(`[Domo.onMatch] .id() must be called before .onMatch(...) in SSG mode`);
+
+      for (const [selector, handler] of Object.entries(selectors)) {
+        this._pushVirtualHandler(elId, event, {
+          type: "match",
+          selector,
+          handler,
+        });
+      }
+
+      return this;
+    }
+
+    return this.on(event, (e) => this._handleMatches(e, selectors), options);
+  }
+}
+
+export default Events;

package/src/properties.js

@@ -0,0 +1,162 @@
+class Properties {
+  /**
+   * Sets a property on the element or its virtual representation.
+   * This is a core internal method used by id(), val(), and txt().
+   * @private
+   * @param {string} key - The property name (e.g., "id", "value", "textContent").
+   * @param {*} val - The value to set for the property.
+   * @param {string} [type="_attr"] - Internal type for virtual DOM handling (e.g., "txt" for textContent).
+   * @returns {this} The current Domo instance for chaining.
+   */
+  _set(key, val, type = "_attr") {
+    if (val === undefined) return this;
+    if (this._isLockedAttr(key)) return this;
+    if (this._virtual) {
+      if (type === "txt") {
+        this.element._child.push(String(val));
+      } else {
+        this.element[type] ??= {};
+        this.element[type][key] = val;
+      }
+    } else {
+      this.element[key] = val;
+    }
+
+    return this;
+  }
+
+  _isLockedAttr(key) {
+    return key === "id" && this._refLocked;
+  }
+
+  /**
+   * Sets the 'id' attribute of the element.
+   * @param {string} id - The ID string to set.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('div').id('myUniqueId');
+   */
+  id(id) {
+    return this._set("id", id);
+  }
+
+  /**
+   * Sets the 'value' property of the element. Useful for input fields, text areas, or select elements.
+   * @param {string} value - The value to set.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('input').val('Initial text');
+   */
+  val(value) {
+    return this._set("value", value);
+  }
+
+  /**
+   * Sets the visible text content of the element. This replaces any existing child text or elements.
+   * @param {string} text - The text string to display.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('p').txt('This is some paragraph text.');
+   */
+  txt(text) {
+    return this._set("textContent", text, "txt");
+  }
+
+  /**
+   * Sets multiple HTML attributes on the element.
+   * Boolean `true` values will set the attribute without a value (e.g., `disabled`).
+   * @param {Record<string, any>} attributes - An object where keys are attribute names and values are their desired values.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('button').attr({
+   * type: 'submit',
+   * disabled: true,
+   * 'aria-label': 'Submit Form'
+   * });
+   */
+  attr(attributes = {}) {
+    for (const [key, value] of Object.entries(attributes)) {
+      if (key.startsWith("on")) continue;
+      if (this._isLockedAttr(key)) continue;
+
+      if (this._virtual) {
+        this.element._attr[key] = value;
+      } else {
+        if (typeof value === "boolean") {
+          value ? this.element.setAttribute(key, "") : this.element.removeAttribute(key);
+        } else if (value != null) {
+          this.element.setAttribute(key, value);
+        }
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Toggles a boolean HTML attribute (e.g., `hidden`, `disabled`) on or off.
+   * @param {string} attrName - The name of the attribute to toggle.
+   * @param {boolean} [force] - If `true`, the attribute is added. If `false`, it's removed.
+   * If omitted, the attribute's presence is flipped.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * // Toggle 'hidden' attribute:
+   * Domo('div').tgglAttr('hidden');
+   * // Force add 'disabled' attribute:
+   * Domo('button').tgglAttr('disabled', true);
+   */
+  tgglAttr(attrName, force) {
+    if (attrName.startsWith("on")) return; // Skip event attributes
+    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 custom `data-*` attributes on the element.
+   * @param {Record<string, string>} data - An object where keys are data attribute names (camelCase) and values are their strings.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('div').data({
+   * userId: '123',
+   * itemName: 'Laptop'
+   * });
+   * // This results in: <div data-user-id="123" data-item-name="Laptop"></div>
+   */
+  data(data = {}) {
+    Object.entries(data).forEach(([key, val]) => {
+      if (this._virtual) this.element._data[key] = val;
+      else this.element.dataset[key] = val;
+    });
+    return this;
+  }
+
+  /**
+   * Applies CSS styles directly to the element's `style` property.
+   * @param {Partial<CSSStyleDeclaration>} styles - An object where keys are CSS property names (camelCase) and values are their style values.
+   * @returns {this} The current Domo instance for chaining.
+   * @example
+   * Domo('p').css({
+   * color: 'blue',
+   * fontSize: '16px',
+   * marginTop: '10px'
+   * });
+   */
+  css(styles = {}) {
+    if (this._virtual) Object.assign(this.element._css, styles);
+    else Object.assign(this.element.style, styles);
+    return this;
+  }
+}
+
+export default Properties;

package/README.md

@@ -1,144 +0,0 @@
-# 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.
-
-### Size
-
-- Minified: 5120 bytes
-- Gzipped: 2054 bytes
-
-Domo is highly optimized for performance, ensuring fast load times even in constrained environments.
-
----
-
-## 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

@@ -1,35 +0,0 @@
-// @ts-check
-
-import DomoClass from "./src/core/Domo.js";
-import Router from "./src/core/Router.js";
-import DomoSVGClass from "./src/core/DomoSVG.js";
-
-/**
- * @typedef {import('./src/core/Domo.js').default} DomoInstance
- * @typedef {import('./src/core/DomoSVG.js').default} DomoSVGInstance
- */
-
-/**
- * @typedef {((tag?: string) => DomoInstance) & { Class: typeof DomoClass }} DomoFactory
- * @typedef {((tag?: string) => DomoSVGInstance)} DomoSVGFactory
- */
-
-/**
- * @param {string} [tag]
- * @returns {DomoInstance}
- */
-function Domo(tag) {
-  return new DomoClass(tag);
-}
-Domo.Class = DomoClass;
-
-/**
- * @param {string} [tag]
- * @returns {DomoSVGInstance}
- */
-function DSVG(tag) {
-  return new DomoSVGClass(tag);
-}
-DSVG.Class = DomoSVGClass;
-
-export { Domo, Router, DSVG, DomoClass };