@twobirds/microcomponents 0.2.1 → 0.2.3

package/dist/types/mcTypes.js

@@ -1,9 +1,9 @@
 /**
-@module Type layer
 
 Pure type layer of the microcomponent system.
 
 RULE: types only — no runtime exports, no imports. It sits at the bottom of the
 dependency graph so every other module can import from it without cycles.
+@module Types
 */
 export {};

package/dist/utils/autoload.d.ts

@@ -1,5 +1,5 @@
 /**
-@module
+@module Autoload
 
 The {@linkcode autoload} function enables automatic detection and instantiation of microcomponents in the DOM via a `MutationObserver`. When enabled, newly added elements with undefined custom tags or `data-mc` references will trigger dynamic script loading and component attachment.
 
@@ -20,6 +20,7 @@ autoload(true);  // enable auto-loading
 console.log(autoload.state); // Set of component names currently loading
 autoload(false); // disable
 ```
+@group Autoload
 */
 export interface Autoload {
     /**
@@ -50,5 +51,8 @@ declare global {
         autoload?: Autoload;
     }
 }
-export declare const autoload: Autoload;
+export declare function autoload(enable?: boolean): boolean;
+export declare namespace autoload {
+    var state: Set<string>;
+}
 //# sourceMappingURL=autoload.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"autoload.d.ts","sourceRoot":"","sources":["../../src/utils/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"}
+{"version":3,"file":"autoload.d.ts","sourceRoot":"","sources":["../../src/utils/autoload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;EASE;AAqJF;;;;;;;;;;;;;EAaE;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,wBAAgB,QAAQ,CAAC,MAAM,GAAE,OAAc,GAAG,OAAO,CAuBxD;yBAvBe,QAAQ"}

package/dist/utils/autoload.js

@@ -1,5 +1,5 @@
 /**
-@module
+@module Autoload
 
 The {@linkcode autoload} function enables automatic detection and instantiation of microcomponents in the DOM via a `MutationObserver`. When enabled, newly added elements with undefined custom tags or `data-mc` references will trigger dynamic script loading and component attachment.
 
@@ -9,7 +9,7 @@ importing `DC`/`MC` never pulls a DOM observer into the bundle unless
 {@link autoload} itself is imported.
 */
 import { DC } from '../core/MC.js';
-import { isMcDOM } from '../core/mcGuards.js';
+import { isMcHost } from '../core/mcGuards.js';
 const loadingDCs = new Set();
 /**
 Creates a closure that attaches DOM elements with the specified tag name to
@@ -24,6 +24,7 @@ element definition becomes available, and performs:
 
 @param element - The tag name (custom element name) of the microcomponent to instantiate.
 @returns A closure that performs the attachment logic when invoked.
+@group Autoload
 */
 function attachDC(element) {
     return () => {
@@ -39,7 +40,7 @@ function attachDC(element) {
                 /* v8 ignore start */
                 if ('create' in customElementClass && typeof customElementClass.create === 'function') {
                     const customElement = customElementClass.create(node);
-                    if (!isMcDOM(customElement))
+                    if (!isMcHost(customElement))
                         throw `create() of Class ${customElementClass.name} did not return a McHost.`;
                     customElement.setAttribute('data-mc', node.getAttribute('data-mc') ?? '');
                     node.replaceWith(customElement);
@@ -135,7 +136,7 @@ function loadUndefinedMCs() {
     });
 }
 let observer = null;
-export const autoload = function (enable = true) {
+export function autoload(enable = true) {
     if (!enable) {
         if (observer) {
             observer.disconnect();
@@ -154,5 +155,6 @@ export const autoload = function (enable = true) {
     }, 5);
     window.autoload ??= autoload;
     return true;
-};
+}
+;
 autoload.state = loadingDCs;

package/dist/utils/events.d.ts

@@ -1,5 +1,5 @@
 /**
-@module
+@module Events
 
 This module provides event utilities for interfacing **between microcomponents and external
 frameworks or native DOM/JS environments**. It is not intended for communication between
@@ -94,91 +94,34 @@ export declare function getMcEventName(eventName: string): string;
  */
 export declare function trueEventName(target: HTMLElement, eventName: string): string;
 /**
- * A query selector string used to match one or more DOM elements.
- *
- * @example
- * ```ts
- * const selector: QuerySelectorString = '.my-component';
- * ```
- */
+A query selector string used to match one or more DOM elements.
+
+@example
+```ts
+const selector: QuerySelectorString = '.my-component';
+```
+@group Events
+*/
 export type QuerySelectorString = string;
 /**
- * Represents the target of an event operation — either a concrete element,
- * a CSS selector string, or `undefined` (which is silently ignored).
- *
- * @example
- * ```ts
- * // Pass an HTMLElement directly
- * const el: TargetSelect = document.getElementById('root');
- *
- * // Or pass a selector string to match multiple elements
- * const allCards: TargetSelect = '.card';
- * ```
- */
+Represents the target of an event operation — either a concrete element,
+a CSS selector string, or `undefined` (which is silently ignored).
+
+@example
+```ts
+// Pass an HTMLElement directly
+const el: TargetSelect = document.getElementById('root');
+
+// Or pass a selector string to match multiple elements
+const allCards: TargetSelect = '.card';
+```
+@group Events
+*/
 export type TargetSelect = HTMLElement | QuerySelectorString | undefined | null;
-/**
- * Removes a previously attached event handler from the DOM node. See {@link on} and {@link one}.
- *
- * Uses internal microcomponent-prefixed naming for event handlers.
- * This is primarily used to interface with external frameworks or vanilla JS environments.
- * For communication between frontend microcomponents, use the `DC.off()` method instead.
- *
- * @param target - The DOM element from which to remove the listener.
- * @param eventName - The name of the event (e.g., 'click', 'update').
- * @param handler - The listener function or object to detach.
- *
- * @example
- * ```ts
- * const handler = on(myElement, 'click', () => console.log('clicked'));
- * off(myElement, 'click', handler); // removes the listener
- * ```
- */
 export declare function off<D = unknown>(target: TargetSelect, eventName: string, handler: McEventHandler<D>): void;
 export declare function off(target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject): void;
-/**
- * Attaches a persistent event listener that will fire every time the specified event occurs.
- *
- * This is primarily used to interface with external frameworks or vanilla JS environments.
- * For communication between frontend microcomponents, use the `DC.on()` method instead.
- *
- * The handler receives a `CustomEvent<McDetail<D>>`: the payload sits under
- * `ev.detail.data`, the bubble-control handle under `ev.detail.control`.
- *
- * @param target - The DOM element to attach the listener to.
- * @param eventName - The name of the event (e.g., 'click', 'update').
- * @param handler - The callback function or object to invoke on each event.
- * @param once - If true, remove the listener after first invocation.
- * @returns The attached handler reference. Useful for later deletion with {@link off}.
- *
- * @example
- * ```ts
- * const handler = on<{ value: number }>(myElement, 'update', (ev) => {
- *     console.log(ev.detail.data.value); // number
- * });
- * // to remove: off(myElement, 'update', handler);
- * ```
- */
 export declare function on<D = unknown>(target: TargetSelect, eventName: string, handler: McEventHandler<D>, once?: boolean): McEventHandler<D>;
 export declare function on(target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject, once?: boolean): EventListenerOrEventListenerObject;
-/**
- * Attaches an event listener that will fire only once.
- *
- * Internally calls {@link on} with the `once` flag set to true. The handler
- * is automatically removed after its first invocation.
- * This is primarily used to interface with external frameworks or vanilla JS environments.
- * For communication between frontend microcomponents, use the `DC.one()` method instead.
- *
- * @param target - The DOM element to attach the listener to.
- * @param eventName - The name of the event (e.g., 'click', 'update').
- * @param handler - The callback function or object to invoke once.
- * @returns The attached one-time handler reference. Useful for later deletion with {@link off}.
- *
- * @example
- * ```ts
- * one<{ ready: boolean }>(myElement, 'dataReady', (ev) => console.log('received:', ev.detail.data));
- * // fires only once then detaches automatically
- * ```
- */
 export declare function one<D = unknown>(target: TargetSelect, eventName: string, handler: McEventHandler<D>): McEventHandler<D>;
 export declare function one(target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDE;AAIF,OAAO,KAAK,EACX,gBAAgB,EAChB,kBAAkB,EAElB,cAAc,EACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;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"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDE;AAIF,OAAO,KAAK,EACX,gBAAgB,EAChB,kBAAkB,EAElB,cAAc,EACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;;EAQE;AACF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;;EAaE;AACF,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAAC;AAEhF,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;AA4CR,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;AAsDtC,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;AA0CtC;;;;;;;;;;;;;;;;;;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"}

package/dist/utils/events.js

@@ -1,5 +1,5 @@
 /**
-@module
+@module Events
 
 This module provides event utilities for interfacing **between microcomponents and external
 frameworks or native DOM/JS environments**. It is not intended for communication between
@@ -99,6 +99,24 @@ export function trueEventName(target, eventName) {
         return lower;
     return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
 }
+/**
+Removes a previously attached event handler from the DOM node. See {@link on} and {@link one}.
+
+Uses internal microcomponent-prefixed naming for event handlers.
+This is primarily used to interface with external frameworks or vanilla JS environments.
+For communication between frontend microcomponents, use the `DC.off()` method instead.
+
+@param target - The DOM element from which to remove the listener.
+@param eventName - The name of the event (e.g., 'click', 'update').
+@param handler - The listener function or object to detach.
+
+@example
+```ts
+const handler = on(myElement, 'click', () => console.log('clicked'));
+off(myElement, 'click', handler); // removes the listener
+```
+@group Events
+*/
 export function off(target, eventName, handler) {
     /* v8 ignore next */
     if (!target)
@@ -113,6 +131,30 @@ export function off(target, eventName, handler) {
     // the cast re-widens it at the DOM boundary.
     target.removeEventListener(trueEventName(target, eventName), handler);
 }
+/**
+Attaches a persistent event listener that will fire every time the specified event occurs.
+
+This is primarily used to interface with external frameworks or vanilla JS environments.
+For communication between frontend microcomponents, use the `DC.on()` method instead.
+
+The handler receives a `CustomEvent<McDetail<D>>`: the payload sits under
+`ev.detail.data`, the bubble-control handle under `ev.detail.control`.
+
+@param target - The DOM element to attach the listener to.
+@param eventName - The name of the event (e.g., 'click', 'update').
+@param handler - The callback function or object to invoke on each event.
+@param once - If true, remove the listener after first invocation.
+@returns The attached handler reference. Useful for later deletion with {@link off}.
+
+@example
+```ts
+const handler = on<{ value: number }>(myElement, 'update', (ev) => {
+    console.log(ev.detail.data.value); // number
+});
+// to remove: off(myElement, 'update', handler);
+```
+@group Events
+*/
 export function on(target, eventName, handler, once = false) {
     /* v8 ignore next */
     if (!target)
@@ -129,6 +171,26 @@ export function on(target, eventName, handler, once = false) {
     });
     return handler;
 }
+/**
+Attaches an event listener that will fire only once.
+
+Internally calls {@link on} with the `once` flag set to true. The handler
+is automatically removed after its first invocation.
+This is primarily used to interface with external frameworks or vanilla JS environments.
+For communication between frontend microcomponents, use the `DC.one()` method instead.
+
+@param target - The DOM element to attach the listener to.
+@param eventName - The name of the event (e.g., 'click', 'update').
+@param handler - The callback function or object to invoke once.
+@returns The attached one-time handler reference. Useful for later deletion with {@link off}.
+
+@example
+```ts
+one<{ ready: boolean }>(myElement, 'dataReady', (ev) => console.log('received:', ev.detail.data));
+// fires only once then detaches automatically
+```
+@group Events
+*/
 export function one(target, eventName, handler) {
     /* v8 ignore next */
     if (!target)

package/dist/utils/helpers.d.ts

@@ -216,7 +216,7 @@ export declare function injectCSS(target: Document | ShadowRoot, css: string): C
  * 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 instance - The micro component to apply assets onto.
  * @param assets - A record mapping asset type keys to their string content.
  *
  * @example
@@ -253,28 +253,29 @@ export declare function processAssets(instance: McController, assets: Record<str
  * });
  * ```
  */
-export declare function loadAssets(name: string, assets: string[]): Promise<string[]>;
+export declare function loadAssets(name: string, assets: string[]): Promise<Array<any>>;
 /**
  * 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`:
+ * 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
+ * - `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.
+ * @param rootElement - The container element whose descendants should be scanned for bindings.
+ * @param instance - The instance to trigger events on.
  *
  * @example
  * ```html
- * <button click="this#onSubmit" payload='{"action":"go"}'>Submit</button>
- * <input change="#cart-form#refresh">
+ * <button click='this|onSubmit|{"action":"go"}'>Submit</button>
+ * <input change="|cart-form|refresh">
  * ```
  */
-export declare function bindTemplateEvents(root: HTMLElement | ShadowRoot, instance: McController): void;
+export declare function bindTemplateEvents(rootElement: 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,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"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;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,CA2B1F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAiC9E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CA2CtG"}

package/dist/utils/helpers.js

@@ -362,7 +362,7 @@ export function injectCSS(target, css) {
  * 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 instance - The micro component to apply assets onto.
  * @param assets - A record mapping asset type keys to their string content.
  *
  * @example
@@ -444,6 +444,16 @@ export function loadAssets(name, assets) {
             if (!resp.ok) {
                 return `file not found: ${filename}`;
             }
+            if (filename.endsWith('json')) {
+                const text = await resp.text();
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    console.error(`could not JSON.parse() asset '${asset}' from ${filename}:\n`, text);
+                    return null;
+                }
+            }
             return resp.text();
         }
         catch {
@@ -456,38 +466,42 @@ export function loadAssets(name, assets) {
  *
  * 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`:
+ * 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
+ * - `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.
+ * @param rootElement - The container element whose descendants should be scanned for bindings.
+ * @param instance - The instance to trigger events on.
  *
  * @example
  * ```html
- * <button click="this#onSubmit" payload='{"action":"go"}'>Submit</button>
- * <input change="#cart-form#refresh">
+ * <button click='this|onSubmit|{"action":"go"}'>Submit</button>
+ * <input change="|cart-form|refresh">
  * ```
  */
-export function bindTemplateEvents(root, instance) {
+export function bindTemplateEvents(rootElement, instance) {
     // Collect all elements that carry at least one attribute matching a native event name.
-    const allElements = root.querySelectorAll('*');
+    const allElements = [...rootElement.querySelectorAll('*')];
     for (const el of allElements) {
         if (!(el instanceof HTMLElement))
             continue;
-        const attrs = Array.from(el.attributes);
+        const attrs = [...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)
+            const parts = attr.value.trim().split('|');
+            if (parts.length < 2)
                 continue; // need at least selector and eventname
+            const [selector, event, payload] = parts;
+            // Clean up binding attributes from the DOM.
+            el.removeAttribute(attr.name);
             // Resolve payload from sibling attribute if present.
             let payloadData; // intentional
             if (payload) {
@@ -507,8 +521,6 @@ export function bindTemplateEvents(root, instance) {
                 // 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/dist/utils/index.d.ts

@@ -0,0 +1,17 @@
+/**
+Utils module — events, autoload, and helper utilities.
+
+@module Utilities
+@showGroups
+*/
+/** @group Events */
+export { getMcEventName, trueEventName, off, on, one, trigger, BubbleController } from './events.js';
+/** @hidden */
+export type { QuerySelectorString, TargetSelect } from './events.js';
+/** @group Autoload */
+export { autoload } from './autoload.js';
+/** @hidden */
+export type { Autoload } from './autoload.js';
+/** @group Helpers */
+export { isBrowser, isNativeObject, sortObject, flattenObject, deepEqual, nameSpace, parse, kebabToPascal, debounce, htmlToElements, copyGettersSetters, injectCSS, processAssets, loadAssets, bindTemplateEvents } from './helpers.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;EAKE;AAEF,oBAAoB;AACpB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACrG,cAAc;AACd,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrE,sBAAsB;AACtB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,cAAc;AACd,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,qBAAqB;AACrB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,kBAAkB,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,12 @@
+/**
+Utils module — events, autoload, and helper utilities.
+
+@module Utilities
+@showGroups
+*/
+/** @group Events */
+export { getMcEventName, trueEventName, off, on, one, trigger, BubbleController } from './events.js';
+/** @group Autoload */
+export { autoload } from './autoload.js';
+/** @group Helpers */
+export { isBrowser, isNativeObject, sortObject, flattenObject, deepEqual, nameSpace, parse, kebabToPascal, debounce, htmlToElements, copyGettersSetters, injectCSS, processAssets, loadAssets, bindTemplateEvents } from './helpers.js';

package/package.json

@@ -1,19 +1,17 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.2.1",
-	"description": "Micro Components Organization Class",
+	"version": "0.2.3",
+	"description": "Micro Components",
 	"keywords": [
-		"API",
-		"DOM manipulation",
-		"ES2015",
-		"ES2016",
-		"ES6",
-		"ES7",
+		"custom elements",
+		"web components",
+		"javascript",
+		"typescript",
 		"PWA",
 		"SPA",
 		"client",
-		"javascript",
 		"library",
+		"framework",
 		"lightweight",
 		"native",
 		"standalone"
@@ -72,20 +70,20 @@
 		"format": "oxfmt .",
 		"lint": "oxlint \"src\"",
 		"fix": "oxfmt . && oxlint \"src\" --fix",
-		"check": "tsc --noEmit -p tsconfig.lib.json && tsc -p tsconfig.test.json && tsc -p tsconfig.demo.json && tsc -p tsconfig.node.json",
+		"check": "tsc --noEmit -p tsconfig.lib.json && tsc -p tsconfig.test.json && tsc -p demo/web-test/tsconfig.demo.json && tsc -p tsconfig.node.json",
 		"check:pack": "publint && attw --pack . --profile esm-only",
 		"test": "vitest",
 		"test:run": "vitest run --reporter=verbose",
 		"test:coverage": "vitest run --coverage",
 		"demo:shop": "vite --config demo/shop/vite.config.ts",
-		"demo:shop:bundled": "tsx vite.shop.bundle.ts",
-		"demo:shop:build": "tsx vite.shop.ts && pnpm run demo:shop:bundled",
+		"demo:shop:bundled": "tsx demo/shop/vite.shop.bundle.ts",
+		"demo:shop:build": "tsx demo/shop/vite.shop.ts && pnpm run demo:shop:bundled",
 		"demo:shop:serve": "vite preview --outDir public/shop --port 5174 --host",
-		"typedoc": "typedoc",
+		"typedoc": "typedoc --displayBasePath ./typedoc/",
 		"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",
+		"demo:build": "tsx demo/web-test/vite.demo.ts",
 		"dev": "vite preview --outDir public/test --port 10000 --host",
 		"doc": "vite preview --outDir public/typedoc --port 11000 --host",
 		"watch": "tsx watch.ts",
@@ -108,5 +106,5 @@
 	"engines": {
 		"node": ">=22.18"
 	},
-	"packageManager": "pnpm@11.15.1"
+	"packageManager": "pnpm@12.4.1"
 }