@twobirds/microcomponents 0.2.0 → 0.2.1

package/dist/{core → utils}/events.js

@@ -57,7 +57,6 @@ off( grandParent, 'dataReady', grandParentHandler );
 ```
 */
 'use strict';
-import { trueEventName } from '../utils/helpers.js';
 /**
  * Converts a standard event name to its microcomponent-prefixed variant.
  *
@@ -74,6 +73,32 @@ import { trueEventName } from '../utils/helpers.js';
 export function getMcEventName(eventName) {
     return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
 }
+/**
+ * Returns the correct event name to listen for on a DOM element.
+ *
+ * If `eventName` (case-insensitive) matches a native HTML event handler property
+ * (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
+ * name so that standard DOM events like `'click'` are listened to correctly.
+ * Otherwise, prefixes with `_mc` for microcomponent custom events.
+ *
+ * @hidden
+ * @param target - The DOM element whose native event support is checked.
+ * @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
+ * @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
+ *
+ * @example
+ * ```ts
+ * const btn = document.createElement('button');
+ * trueEventName(btn, 'Click');   // 'click'  — native handler exists
+ * trueEventName(btn, 'Update');  // '_mcUpdate' — custom event
+ * ```
+ */
+export function trueEventName(target, eventName) {
+    const lower = eventName.toLowerCase();
+    if ('on' + lower in target)
+        return lower;
+    return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
+}
 export function off(target, eventName, handler) {
     /* v8 ignore next */
     if (!target)

package/dist/utils/helpers.d.ts

@@ -5,6 +5,7 @@ Small runtime-agnostic utilities shared across the library: environment
 detection, object flattening/comparison, debouncing, accessor copying, and
 kebab-to-PascalCase conversion.
 */
+import type { McController } from '../types/mcTypes.js';
 /**
  * Determines whether the current runtime environment is a web browser.
  *
@@ -147,6 +148,7 @@ export declare function debounce<A extends unknown[]>(func: (...args: A) => unkn
 /**
  * Parses an HTML string and returns an array of DOM elements.
  * Handles self-closing tags (XHTML style) by converting them to full closing tags first.
+ * @hidden
  * @param html - The HTML string to parse.
  * @returns An array of HTMLElement objects representing the parsed HTML nodes.
  *
@@ -157,29 +159,10 @@ export declare function debounce<A extends unknown[]>(func: (...args: A) => unkn
  * ```
  */
 export declare function htmlToElements(html: string): HTMLElement[];
-/**
- * Returns the correct event name to listen for on a DOM element.
- *
- * If `eventName` (case-insensitive) matches a native HTML event handler property
- * (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
- * name so that standard DOM events like `'click'` are listened to correctly.
- * Otherwise, prefixes with `_mc` for microcomponent custom events.
- *
- * @param target - The DOM element whose native event support is checked.
- * @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
- * @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
- *
- * @example
- * ```ts
- * const btn = document.createElement('button');
- * trueEventName(btn, 'Click');   // 'click'  — native handler exists
- * trueEventName(btn, 'Update');  // '_mcUpdate' — custom event
- * ```
- */
-export declare function trueEventName(target: HTMLElement, eventName: string): string;
 /**
  * Copies all getter and setter properties from a source object to a target object.
  * Does not copy methods or regular data properties—only accessor properties (get/set).
+ * @hidden
  * @param source - The source object with getters and/or setters to copy.
  * @param target - The target object to which the accessors will be copied.
  *
@@ -192,4 +175,106 @@ export declare function trueEventName(target: HTMLElement, eventName: string): s
  * ```
  */
 export declare function copyGettersSetters(source: object, target: object): void;
+/**
+ * Injects a CSS string into the given scope (document or shadow root) as an adopted stylesheet.
+ * Enables css-in-js so that every custom element is self-contained and importable.
+ *
+ * @hidden
+ * @param target - The scope to inject styles into: `document` for global styles, or a `ShadowRoot` for encapsulated component internals.
+ * @param css - The CSS string to inject.
+ * @returns The created `CSSStyleSheet` instance that was adopted into the target scope.
+ *
+ * When targeting **document**: selectors like `:host`, `::slotted()`, and shadow-internal classes are **not allowed** — they have no effect outside a shadow root. Use only global selectors, element tags, or layout presets.
+ * When targeting **shadowRoot**: use `:host` for the custom element itself, standard selectors (`.inner`, `#id`) for internal structure, and `::slotted()` for projected light-DOM content.
+ *
+ * @example Inject global styles into the document:
+ * ```ts
+ * import { injectCSS } from '@twobirds/mc/utils/helpers';
+ * injectCSS(document, 'body { display: block; }');
+ * ```
+ *
+ * @example Inject global styles for a micro component into the document:
+ * ```ts
+ * import { injectCSS } from '@twobirds/mc/utils/helpers';
+ * injectCSS(document, 'my-microcomponent { display: block; }');
+ * ```
+ *
+ * @example Inject scoped styles into a shadow root:
+ * ```ts
+ * const shadow = element.attachShadow({ mode: 'open' });
+ * injectCSS(shadow, ':host { color: var(--text); } .inner { padding: 8px; }');
+ * ```
+ * Styles can also be added using a compound innerHTML statement: `shadow.innerHTML = \`<style>${style}</style>${template}\``
+ */
+export declare function injectCSS(target: Document | ShadowRoot, css: string): CSSStyleSheet;
+/**
+ * Processes a record of asset strings and applies them to the given target element.
+ * Supports injecting CSS into document or shadow root, and setting innerHTML for
+ * both target and shadow DOM. Automatically attaches a shadow root if any key starts
+ * with `'shadow'`.
+ *
+ * Recognized keys: `'css'`, `'targetCss'` (document-level styles), `'shadowCss'`
+ * (shadow-root styles), `'shadowHtml'` (shadow innerHTML), `'targetHtml'` (target innerHTML).
+ *
+ * @param target - The HTMLElement to apply assets onto.
+ * @param assets - A record mapping asset type keys to their string content.
+ *
+ * @example
+ * ```ts
+ * processAssets(this, {
+ *   css: 'body { margin: 0; }',
+ *   shadowCss: ':host { display: block; }',
+ *   shadowHtml: '<slot></slot>'
+ * });
+ * ```
+ */
+export declare function processAssets(instance: McController, assets: Record<string, string>): void;
+/**
+ * Loads companion asset files (CSS, HTML) for a given component basename from the server.
+ *
+ * Each entry in `assets` encodes an optional variant and extension in camelCase, e.g. `'shadowCss'` → `{name}.shadow.css`,
+ * `'targetHtml'` → `{name}.target.html`. Plain entries like `'css'` or `'html'` resolve to
+ * `{name}.css` / `{name}.html`.
+ *
+ * In bundled mode the Vite plugin replaces this call with an inline array literal, so `.then()`
+ * fires synchronously — no async overhead.
+ *
+ * @hidden
+ * @param name - The component basename (e.g. `'shop-catalog'`).
+ * @param assets - Array of asset descriptors such as `'shadowCss'`, `'targetHtml'`, `'shadowHtml'`, `'css'`, `'html'`.
+ * @returns A promise resolving to an array of file contents in the same order as `assets`. If a file is not found, the corresponding entry is `'file not found: ' + filename`.
+ *
+ * @example
+ * ```ts
+ * export const MyComponent = loadAssets('my-component', ['shadowCss', 'shadowHtml']).then(([shadowCss, shadowHtml]) => {
+ *   class _MyComponent extends DC { ... }
+ *   defineCE('my-component', _MyComponent);
+ *   return _MyComponent;
+ * });
+ * ```
+ */
+export declare function loadAssets(name: string, assets: string[]): Promise<string[]>;
+/**
+ * Binds declarative event attributes in a template fragment to microcomponent triggers.
+ *
+ * Scans all elements under `root` for attributes whose names correspond to native DOM
+ * events (e.g. `click`, `submit`, `change`). The attribute value encodes the target and
+ * handler method in the form `target#methodName`:
+ *
+ * - `this#myHandler` — triggers locally on the component attached to this element.
+ * - `#other-comp#submit` — resolves elements via `querySelectorAll('#other-comp')` and
+ *   triggers the event on each matched host's `_mc`.
+ *
+ * An optional sibling `payload` attribute supplies the data argument for `trigger()`.
+ * After binding, both the event attribute and the payload attribute are removed from the DOM.
+ *
+ * @param root - The container element whose descendants should be scanned for bindings.
+ *
+ * @example
+ * ```html
+ * <button click="this#onSubmit" payload='{"action":"go"}'>Submit</button>
+ * <input change="#cart-form#refresh">
+ * ```
+ */
+export declare function bindTemplateEvents(root: HTMLElement | ShadowRoot, instance: McController): void;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/utils/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAiB1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqB7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAiCzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,GAAE,MAAW,GAAG,OAAO,CAe1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,EACpD,QAAQ,EAAE,CAAC,EACX,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,OAAO,EAAE,GAChB,CAAC,CAgCH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,UAKxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAC3C,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,EAC7B,YAAY,EAAE,MAAM,GAClB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAStB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAU1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOvE"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,YAAY,EAAU,MAAM,qBAAqB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAiB1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqB7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAiCzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,GAAE,MAAW,GAAG,OAAO,CAe1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,EACpD,QAAQ,EAAE,CAAC,EACX,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,OAAO,EAAE,GAChB,CAAC,CAgCH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,UAKxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAC3C,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,EAC7B,YAAY,EAAE,MAAM,GAClB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAStB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAU1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAOnF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CA4B1F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwB5E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CA0C/F"}

package/dist/utils/helpers.js

@@ -5,6 +5,7 @@ Small runtime-agnostic utilities shared across the library: environment
 detection, object flattening/comparison, debouncing, accessor copying, and
 kebab-to-PascalCase conversion.
 */
+import { on, trigger } from './events.js';
 /**
  * Determines whether the current runtime environment is a web browser.
  *
@@ -275,6 +276,7 @@ export function debounce(func, milliseconds) {
 /**
  * Parses an HTML string and returns an array of DOM elements.
  * Handles self-closing tags (XHTML style) by converting them to full closing tags first.
+ * @hidden
  * @param html - The HTML string to parse.
  * @returns An array of HTMLElement objects representing the parsed HTML nodes.
  *
@@ -291,34 +293,10 @@ export function htmlToElements(html) {
     template.content.normalize();
     return Array.from(template.content.childNodes);
 }
-/**
- * Returns the correct event name to listen for on a DOM element.
- *
- * If `eventName` (case-insensitive) matches a native HTML event handler property
- * (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
- * name so that standard DOM events like `'click'` are listened to correctly.
- * Otherwise, prefixes with `_mc` for microcomponent custom events.
- *
- * @param target - The DOM element whose native event support is checked.
- * @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
- * @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
- *
- * @example
- * ```ts
- * const btn = document.createElement('button');
- * trueEventName(btn, 'Click');   // 'click'  — native handler exists
- * trueEventName(btn, 'Update');  // '_mcUpdate' — custom event
- * ```
- */
-export function trueEventName(target, eventName) {
-    const lower = eventName.toLowerCase();
-    if ('on' + lower in target)
-        return lower;
-    return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
-}
 /**
  * Copies all getter and setter properties from a source object to a target object.
  * Does not copy methods or regular data properties—only accessor properties (get/set).
+ * @hidden
  * @param source - The source object with getters and/or setters to copy.
  * @param target - The target object to which the accessors will be copied.
  *
@@ -338,3 +316,199 @@ export function copyGettersSetters(source, target) {
         }
     }
 }
+/**
+ * Injects a CSS string into the given scope (document or shadow root) as an adopted stylesheet.
+ * Enables css-in-js so that every custom element is self-contained and importable.
+ *
+ * @hidden
+ * @param target - The scope to inject styles into: `document` for global styles, or a `ShadowRoot` for encapsulated component internals.
+ * @param css - The CSS string to inject.
+ * @returns The created `CSSStyleSheet` instance that was adopted into the target scope.
+ *
+ * When targeting **document**: selectors like `:host`, `::slotted()`, and shadow-internal classes are **not allowed** — they have no effect outside a shadow root. Use only global selectors, element tags, or layout presets.
+ * When targeting **shadowRoot**: use `:host` for the custom element itself, standard selectors (`.inner`, `#id`) for internal structure, and `::slotted()` for projected light-DOM content.
+ *
+ * @example Inject global styles into the document:
+ * ```ts
+ * import { injectCSS } from '@twobirds/mc/utils/helpers';
+ * injectCSS(document, 'body { display: block; }');
+ * ```
+ *
+ * @example Inject global styles for a micro component into the document:
+ * ```ts
+ * import { injectCSS } from '@twobirds/mc/utils/helpers';
+ * injectCSS(document, 'my-microcomponent { display: block; }');
+ * ```
+ *
+ * @example Inject scoped styles into a shadow root:
+ * ```ts
+ * const shadow = element.attachShadow({ mode: 'open' });
+ * injectCSS(shadow, ':host { color: var(--text); } .inner { padding: 8px; }');
+ * ```
+ * Styles can also be added using a compound innerHTML statement: `shadow.innerHTML = \`<style>${style}</style>${template}\``
+ */
+export function injectCSS(target, css) {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(css);
+    target.adoptedStyleSheets.push(sheet);
+    return sheet;
+}
+/**
+ * Processes a record of asset strings and applies them to the given target element.
+ * Supports injecting CSS into document or shadow root, and setting innerHTML for
+ * both target and shadow DOM. Automatically attaches a shadow root if any key starts
+ * with `'shadow'`.
+ *
+ * Recognized keys: `'css'`, `'targetCss'` (document-level styles), `'shadowCss'`
+ * (shadow-root styles), `'shadowHtml'` (shadow innerHTML), `'targetHtml'` (target innerHTML).
+ *
+ * @param target - The HTMLElement to apply assets onto.
+ * @param assets - A record mapping asset type keys to their string content.
+ *
+ * @example
+ * ```ts
+ * processAssets(this, {
+ *   css: 'body { margin: 0; }',
+ *   shadowCss: ':host { display: block; }',
+ *   shadowHtml: '<slot></slot>'
+ * });
+ * ```
+ */
+export function processAssets(instance, assets) {
+    const target = instance.target;
+    let shadow = target.shadowRoot;
+    if (!shadow && Object.keys(assets).some((key) => key.indexOf('shadow') === 0)) {
+        shadow = target.attachShadow({ mode: 'open' });
+    }
+    Object.keys(assets).forEach((key) => {
+        switch (key) {
+            case 'css':
+                injectCSS(document, assets[key]);
+                break;
+            case 'targetCss':
+                injectCSS(document, assets[key]);
+                break;
+            case 'shadowCss':
+                injectCSS(shadow, assets[key]);
+                break;
+            case 'shadowHtml':
+                shadow.innerHTML = assets[key];
+                bindTemplateEvents(shadow, instance);
+                break;
+            case 'targetHtml':
+                target.innerHTML = assets[key];
+                bindTemplateEvents(target, instance);
+                break;
+        }
+    });
+}
+/**
+ * Loads companion asset files (CSS, HTML) for a given component basename from the server.
+ *
+ * Each entry in `assets` encodes an optional variant and extension in camelCase, e.g. `'shadowCss'` → `{name}.shadow.css`,
+ * `'targetHtml'` → `{name}.target.html`. Plain entries like `'css'` or `'html'` resolve to
+ * `{name}.css` / `{name}.html`.
+ *
+ * In bundled mode the Vite plugin replaces this call with an inline array literal, so `.then()`
+ * fires synchronously — no async overhead.
+ *
+ * @hidden
+ * @param name - The component basename (e.g. `'shop-catalog'`).
+ * @param assets - Array of asset descriptors such as `'shadowCss'`, `'targetHtml'`, `'shadowHtml'`, `'css'`, `'html'`.
+ * @returns A promise resolving to an array of file contents in the same order as `assets`. If a file is not found, the corresponding entry is `'file not found: ' + filename`.
+ *
+ * @example
+ * ```ts
+ * export const MyComponent = loadAssets('my-component', ['shadowCss', 'shadowHtml']).then(([shadowCss, shadowHtml]) => {
+ *   class _MyComponent extends DC { ... }
+ *   defineCE('my-component', _MyComponent);
+ *   return _MyComponent;
+ * });
+ * ```
+ */
+export function loadAssets(name, assets) {
+    const parseAsset = (asset) => {
+        // Match camelCase variant+ext, e.g. 'shadowCss' → ['shadow','css']
+        const m = asset.match(/^([a-z]+)([A-Z][a-z]*)$/);
+        if (m) {
+            return `./${name.replace(/-/g, '/')}.${m[1]}.${m[2].toLowerCase()}`;
+        }
+        // Plain extension, e.g. 'css' → 'catalog.css'
+        return `./${name.replace(/-/g, '/')}.${asset.toLowerCase()}`;
+    };
+    return Promise.all(assets.map(async (asset) => {
+        const filename = parseAsset(asset);
+        //console.log(filename);
+        try {
+            const resp = await fetch(filename);
+            if (!resp.ok) {
+                return `file not found: ${filename}`;
+            }
+            return resp.text();
+        }
+        catch {
+            return `file not found: ${filename}`;
+        }
+    }));
+}
+/**
+ * Binds declarative event attributes in a template fragment to microcomponent triggers.
+ *
+ * Scans all elements under `root` for attributes whose names correspond to native DOM
+ * events (e.g. `click`, `submit`, `change`). The attribute value encodes the target and
+ * handler method in the form `target#methodName`:
+ *
+ * - `this#myHandler` — triggers locally on the component attached to this element.
+ * - `#other-comp#submit` — resolves elements via `querySelectorAll('#other-comp')` and
+ *   triggers the event on each matched host's `_mc`.
+ *
+ * An optional sibling `payload` attribute supplies the data argument for `trigger()`.
+ * After binding, both the event attribute and the payload attribute are removed from the DOM.
+ *
+ * @param root - The container element whose descendants should be scanned for bindings.
+ *
+ * @example
+ * ```html
+ * <button click="this#onSubmit" payload='{"action":"go"}'>Submit</button>
+ * <input change="#cart-form#refresh">
+ * ```
+ */
+export function bindTemplateEvents(root, instance) {
+    // Collect all elements that carry at least one attribute matching a native event name.
+    const allElements = root.querySelectorAll('*');
+    for (const el of allElements) {
+        if (!(el instanceof HTMLElement))
+            continue;
+        const attrs = Array.from(el.attributes);
+        for (const attr of attrs) {
+            const lowerName = attr.name.toLowerCase();
+            // Check if this attribute name maps to a native event handler property.
+            if (!('on' + lowerName in el))
+                continue;
+            const [selector, event, payload] = attr.value.trim().split('#');
+            if (!event)
+                continue; // need at least selector and eventname
+            // Resolve payload from sibling attribute if present.
+            let payloadData; // intentional
+            if (payload) {
+                try {
+                    payloadData = JSON.parse(payload);
+                }
+                catch {
+                    payloadData = payload;
+                }
+            }
+            // Wire the native event listener.
+            if (selector === 'this' || selector === '') {
+                // Local trigger — fire on the _mc attached to this element.
+                on(el, lowerName, () => instance.trigger(event, payloadData));
+            }
+            else {
+                // Selector-based trigger — query and fire on every match.
+                on(el, lowerName, () => trigger(selector, event, payloadData));
+            }
+            // Clean up binding attributes from the DOM.
+            el.removeAttribute(attr.name);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Micro Components Organization Class",
 	"keywords": [
 		"API",
@@ -51,8 +51,8 @@
 			"import": "./dist/core/mcGuards.js"
 		},
 		"./events": {
-			"types": "./dist/core/events.d.ts",
-			"import": "./dist/core/events.js"
+			"types": "./dist/utils/events.d.ts",
+			"import": "./dist/utils/events.js"
 		},
 		"./elements": {
 			"types": "./dist/core/elements.d.ts",
@@ -78,17 +78,17 @@
 		"test:run": "vitest run --reporter=verbose",
 		"test:coverage": "vitest run --coverage",
 		"demo:shop": "vite --config demo/shop/vite.config.ts",
-		"demo:shop:bundled": "node vite.shop.bundle.ts",
-		"demo:shop:build": "node vite.shop.ts && pnpm run demo:shop:bundled",
+		"demo:shop:bundled": "tsx vite.shop.bundle.ts",
+		"demo:shop:build": "tsx vite.shop.ts && pnpm run demo:shop:bundled",
 		"demo:shop:serve": "vite preview --outDir public/shop --port 5174 --host",
 		"typedoc": "typedoc",
-		"bundle": "node vite.build.ts",
-		"clean": "rm -rf dist public",
-		"build": "pnpm run clean && tsc -p tsconfig.lib.json && pnpm run test:coverage && pnpm run bundle && pnpm run check:pack && pnpm run typedoc && pnpm run demo:build && pnpm run demo:shop:build",
-		"demo:build": "node vite.demo.ts",
+		"bundle": "tsx vite.build.ts",
+		"clean": "rm -rf dist public build",
+		"build": "pnpm run clean && tsc -p tsconfig.lib.json && pnpm run test:coverage && pnpm run bundle && pnpm run check:pack && pnpm run typedoc && pnpm run demo:build && pnpm run demo:shop:build && find src -name '*.js' -delete",
+		"demo:build": "tsx vite.demo.ts",
 		"dev": "vite preview --outDir public/test --port 10000 --host",
 		"doc": "vite preview --outDir public/typedoc --port 11000 --host",
-		"watch": "node watch.ts",
+		"watch": "tsx watch.ts",
 		"prepublishOnly": "pnpm run build && pnpm run check"
 	},
 	"devDependencies": {
@@ -99,6 +99,7 @@
 		"oxfmt": "^0.59.0",
 		"oxlint": "^1.74.0",
 		"publint": "^0.3.21",
+		"tsx": "^4.23.12",
 		"typedoc": "^0.28.20",
 		"typescript": "^6.0.3",
 		"vite": "^8.1.5",

package/dist/core/autoload.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"autoload.d.ts","sourceRoot":"","sources":["../../src/core/autoload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;EASE;AAoJF;;;;;;;;;;;;EAYE;AACF,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;IAaG;IACH,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5B;;;;;IAKG;IACH,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACnB;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;KACpB;CACD;AAID,eAAO,MAAM,QAAQ,EAAE,QAuBtB,CAAC"}

package/dist/core/events.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDE;AAIF,OAAO,KAAK,EACX,gBAAgB,EAChB,kBAAkB,EAElB,cAAc,EACd,MAAM,qBAAqB,CAAC;AAG7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAAC;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,IAAI,CAAC;AACR,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,IAAI,CAAC;AA0BR;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,EAAE,CAAC,CAAC,GAAG,OAAO,EAC7B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,IAAI,CAAC,EAAE,OAAO,GACZ,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,EAAE,CACjB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,EAC3C,IAAI,CAAC,EAAE,OAAO,GACZ,kCAAkC,CAAC;AA8BtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC,CAAC;AAsBtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IAC1D,OAAO,UAAS;;IAEhB;;;;;;;;;;;;;;;OAeG;IACH,IAAI;CAGJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAClC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,CAAW,EACjB,MAAM,GAAE,gBAAsB,EAAE,wBAAwB;AACxD,UAAU,CAAC,EAAE,gBAAgB,QA+C7B"}