@twobirds/microcomponents 0.9.0 → 0.10.1

package/dist/utils/events.js

@@ -1,3 +1,4 @@
+//#region src/utils/events.ts
 /**
 @module Events
 
@@ -18,10 +19,10 @@ The core feature is the ability to explicitly control event flow direction when
 html:
 ```html
 <div class="grandparent">
-    <div class="parent">
-        <div class="child">
-        </div>
-    </div>
+<div class="parent">
+<div class="child">
+</div>
+</div>
 </div>
 ```
 
@@ -48,52 +49,50 @@ The `dataReady` event bubbles upward from the innermost `div`, but `parentHandle
 calls `ev.detail.control.stop()`, so the `grandParent` handler is never reached.
 Handlers are detached with `off()` once they are no longer needed.
 */
-'use strict';
 /**
- * Converts a standard event name to its microcomponent-prefixed variant.
- *
- * This utility is used internally to namespace custom events (e.g., 'Click' → '_mcClick').
- *
- * @param eventName - The original event name (e.g., 'click', 'update').
- * @returns The microcomponent-prefixed event name.
- *
- * @example
- * ```ts
- * console.log(getMcEventName('update'));
- * ```
- */
-export function getMcEventName(eventName) {
-    return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
+* Converts a standard event name to its microcomponent-prefixed variant.
+*
+* This utility is used internally to namespace custom events (e.g., 'Click' → '_mcClick').
+*
+* @param eventName - The original event name (e.g., 'click', 'update').
+* @returns The microcomponent-prefixed event name.
+*
+* @example
+* ```ts
+* console.log(getMcEventName('update'));
+* ```
+*/
+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');
- * console.log(trueEventName(btn, 'Click'));
- * console.log(trueEventName(btn, 'Update'));
- * ```
- *
- * `'Click'` resolves to the native `'click'` because the button has an `onclick` handler
- * property; `'Update'` has no native counterpart, so it becomes the `_mc`-prefixed custom
- * event name.
- */
-export function trueEventName(target, eventName) {
-    const lower = eventName.toLowerCase();
-    if ('on' + lower in target)
-        return lower;
-    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');
+* console.log(trueEventName(btn, 'Click'));
+* console.log(trueEventName(btn, 'Update'));
+* ```
+*
+* `'Click'` resolves to the native `'click'` because the button has an `onclick` handler
+* property; `'Update'` has no native counterpart, so it becomes the `_mc`-prefixed custom
+* event name.
+*/
+function trueEventName(target, eventName) {
+	const lower = eventName.toLowerCase();
+	if ("on" + lower in target) 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}.
@@ -113,19 +112,14 @@ off(myElement, 'click', handler);
 ```
 @group Events
 */
-export function off(target, eventName, handler) {
-    /* v8 ignore next */
-    if (!target)
-        return;
-    if (typeof target === 'string') {
-        document
-            .querySelectorAll(target)
-            .forEach((el) => off(el, eventName, handler));
-        return;
-    }
-    // McEventHandler<D> narrows the runtime EventListener contract type-side only;
-    // the cast re-widens it at the DOM boundary.
-    target.removeEventListener(trueEventName(target, eventName), handler);
+function off(target, eventName, handler) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => off(el, eventName, handler));
+		return;
+	}
+	target.removeEventListener(trueEventName(target, eventName), handler);
 }
 /**
 Attaches a persistent event listener that will fire every time the specified event occurs.
@@ -145,27 +139,24 @@ The handler receives a `CustomEvent<McDetail<D>>`: the payload sits under
 @example
 ```ts
 const handler = on<{ value: number }>(myElement, 'update', (ev) => {
-    console.log(ev.detail.data.value);
+console.log(ev.detail.data.value);
 });
 off(myElement, 'update', handler);
 ```
 @group Events
 */
-export function on(target, eventName, handler, once = false) {
-    /* v8 ignore next */
-    if (!target)
-        return;
-    if (typeof target === 'string') {
-        document
-            .querySelectorAll(target)
-            .forEach((el) => on(el, eventName, handler));
-        return;
-    }
-    target.addEventListener(trueEventName(target, eventName), handler, {
-        capture: false,
-        once,
-    });
-    return handler;
+function on(target, eventName, handler, once = false) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => on(el, eventName, handler));
+		return;
+	}
+	target.addEventListener(trueEventName(target, eventName), handler, {
+		capture: false,
+		once
+	});
+	return handler;
 }
 /**
 Attaches an event listener that will fire only once.
@@ -188,128 +179,111 @@ one<{ ready: boolean }>(myElement, 'dataReady', (ev) => console.log('received:',
 The listener fires only once and detaches automatically.
 @group Events
 */
-export function one(target, eventName, handler) {
-    /* v8 ignore next */
-    if (!target)
-        return;
-    if (typeof target === 'string') {
-        document
-            .querySelectorAll(target)
-            .forEach((el) => one(el, eventName, handler));
-        return;
-    }
-    on(target, eventName, handler, true); // true indicates once
-    return handler;
+function one(target, eventName, handler) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => one(el, eventName, handler));
+		return;
+	}
+	on(target, eventName, handler, true);
+	return handler;
 }
 /**
- * @hidden
- * A controller object used to manage and potentially abort event bubbling.
- *
- * The `trigger()` function internally creates instance of this class,
- * allowing the an eventual handler to call `ev.detail.control.stop()` to
- * prevent further propagation in either direction (up/down).
- *
- * This is only used internally.
- * @example
- * ```ts
- * trigger(myElement, 'update', { value: 42 }, 'u');
- *
- * onUpdate(ev) {
- *     ev.detail.control.stop();
- * }
- * ```
- */
-export class BubbleController {
-    stopped = false;
-    constructor() { }
-    /**
-     * Signals that event bubbling should be halted.
-     *
-     * After calling this method, subsequent `trigger()` calls will abort
-     * before dispatching the event to any targets.
-     *
-     * @example
-     * ```ts
-     * trigger(myElement, 'update', { value: 42 }, 'u');
-     *
-     * onUpdate(ev) {
-     *     ev.detail.control.stop();
-     * }
-     * ```
-     */
-    stop() {
-        this.stopped = true;
-    }
-}
+* @hidden
+* A controller object used to manage and potentially abort event bubbling.
+*
+* The `trigger()` function internally creates instance of this class,
+* allowing the an eventual handler to call `ev.detail.control.stop()` to
+* prevent further propagation in either direction (up/down).
+*
+* This is only used internally.
+* @example
+* ```ts
+* trigger(myElement, 'update', { value: 42 }, 'u');
+*
+* onUpdate(ev) {
+*     ev.detail.control.stop();
+* }
+* ```
+*/
+var BubbleController = class {
+	stopped = false;
+	constructor() {}
+	/**
+	* Signals that event bubbling should be halted.
+	*
+	* After calling this method, subsequent `trigger()` calls will abort
+	* before dispatching the event to any targets.
+	*
+	* @example
+	* ```ts
+	* trigger(myElement, 'update', { value: 42 }, 'u');
+	*
+	* onUpdate(ev) {
+	*     ev.detail.control.stop();
+	* }
+	* ```
+	*/
+	stop() {
+		this.stopped = true;
+	}
+};
 /**
- * Creates and dispatches a custom event on the specified DOM node.
- *
- * The event is namespaced with an `_mc` prefix by default, unless already prefixed.
- * Supports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:
- * - 'l': local dispatch only
- * - 'u': bubble up towards ancestors
- * - 'd': bubble down to descendants
- *
- * The dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload
- * under `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.
- *
- * Prefer a direct target over bubbling: name the receiving element in `target` and keep the
- * default `'l'`, so one `querySelectorAll` reaches it in a single step. Reserve `'u'`/`'d'`
- * for receivers that cannot be named in advance, since they walk the tree and re-dispatch the
- * event at every level. Pass a typed object as `data` rather than a bare string, so the
- * handler reads named fields from `ev.detail.data` and the flow stays readable as it grows.
- *
- * @param target - The DOM element on which to trigger the event, or a querySelectorAll(selector) selector string.
- * @param event - The name of the event (will be prefixed if needed).
- * @param data - Additional data payload attached to `event.detail.data`.
- * @param bubble - Bubbling direction ('l', 'u', 'd' or combinations).
- * @param controller - Optional controller for managing bubbling behavior.
- *
- * @example
- * ```ts
- * trigger(myElement, 'update', { value: 42 }, 'l');
- * trigger(myElement, 'dataReady', { ready: true }, 'u');
- * ```
- *
- * The first dispatch fires locally only; the second bubbles upward to ancestor components.
- */
-export function trigger(target, event, data = {}, bubble = 'l', // direction of bubbling
-controller) {
-    /* v8 ignore next */
-    if (!target)
-        return;
-    if (typeof target === 'string') {
-        document
-            .querySelectorAll(target)
-            .forEach((el) => trigger(el, event, data, bubble));
-        return;
-    }
-    const eventName = /^_mc/.test(event) ? event : trueEventName(target, event), bubbleController = controller ? controller : new BubbleController(), ev = new CustomEvent(eventName, {
-        detail: { data, control: bubbleController },
-        bubbles: false,
-    });
-    if (bubbleController.stopped) {
-        return;
-    }
-    if (/l/.test(bubble)) {
-        target.dispatchEvent(ev);
-        if (bubbleController.stopped) {
-            return;
-        }
-    }
-    // bubble if up or down is indicated
-    if (/[ud]/.test(bubble)) {
-        queueMicrotask(() => {
-            // bubble up towards document.body
-            if (bubble.indexOf('u') > -1) {
-                trigger(target.parentElement, eventName, data, 'lu', bubbleController);
-            }
-            // bubble down towards DOM children
-            if (bubble.indexOf('d') > -1) {
-                for (const child of target.children) {
-                    trigger(child, eventName, data, 'ld'); // event multiplex - dont carry bubble controller
-                }
-            }
-        });
-    }
+* Creates and dispatches a custom event on the specified DOM node.
+*
+* The event is namespaced with an `_mc` prefix by default, unless already prefixed.
+* Supports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:
+* - 'l': local dispatch only
+* - 'u': bubble up towards ancestors
+* - 'd': bubble down to descendants
+*
+* The dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload
+* under `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.
+*
+* Prefer a direct target over bubbling: name the receiving element in `target` and keep the
+* default `'l'`, so one `querySelectorAll` reaches it in a single step. Reserve `'u'`/`'d'`
+* for receivers that cannot be named in advance, since they walk the tree and re-dispatch the
+* event at every level. Pass a typed object as `data` rather than a bare string, so the
+* handler reads named fields from `ev.detail.data` and the flow stays readable as it grows.
+*
+* @param target - The DOM element on which to trigger the event, or a querySelectorAll(selector) selector string.
+* @param event - The name of the event (will be prefixed if needed).
+* @param data - Additional data payload attached to `event.detail.data`.
+* @param bubble - Bubbling direction ('l', 'u', 'd' or combinations).
+* @param controller - Optional controller for managing bubbling behavior.
+*
+* @example
+* ```ts
+* trigger(myElement, 'update', { value: 42 }, 'l');
+* trigger(myElement, 'dataReady', { ready: true }, 'u');
+* ```
+*
+* The first dispatch fires locally only; the second bubbles upward to ancestor components.
+*/
+function trigger(target, event, data = {}, bubble = "l", controller) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => trigger(el, event, data, bubble));
+		return;
+	}
+	const eventName = /^_mc/.test(event) ? event : trueEventName(target, event), bubbleController = controller ? controller : new BubbleController(), ev = new CustomEvent(eventName, {
+		detail: {
+			data,
+			control: bubbleController
+		},
+		bubbles: false
+	});
+	if (bubbleController.stopped) return;
+	if (/l/.test(bubble)) {
+		target.dispatchEvent(ev);
+		if (bubbleController.stopped) return;
+	}
+	if (/[ud]/.test(bubble)) queueMicrotask(() => {
+		if (bubble.indexOf("u") > -1) trigger(target.parentElement, eventName, data, "lu", bubbleController);
+		if (bubble.indexOf("d") > -1) for (const child of target.children) trigger(child, eventName, data, "ld");
+	});
 }
+//#endregion
+export { BubbleController, getMcEventName, off, on, one, trigger, trueEventName };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.9.0",
+	"version": "0.10.1",
 	"description": "Micro Components",
 	"keywords": [
 		"PWA",
@@ -73,17 +73,13 @@
 			"types": "./dist/mcp/index.d.ts",
 			"import": "./dist/mcp/index.js"
 		},
-		"./vite": {
-			"types": "./dist/vite/index.d.ts",
-			"import": "./dist/vite/index.js"
-		},
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"format": "oxfmt .",
 		"lint": "oxlint \"src\"",
 		"fix": "oxfmt . && oxlint \"src\" --fix",
-		"check": "tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.cli.json && tsc --noEmit -p tsconfig.mcp.json && tsc -p tsconfig.test.json && tsc -p demo/web-test/tsconfig.demo.json && tsc --noEmit -p demo/shop/tsconfig.demo.json && tsc --noEmit -p demo/todo_mvc/tsconfig.demo.json && tsc -p tsconfig.node.json",
+		"check": "tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.cli.json && tsc --noEmit -p tsconfig.mcp.json && tsc -p tsconfig.test.json && tsc -p demo/web-test/tsconfig.demo.json && tsc --noEmit -p demo/shop/tsconfig.demo.json && tsc --noEmit -p demo/todo_mvc/tsconfig.demo.json && tsc --noEmit -p demo/docs/tsconfig.demo.json && tsc -p tsconfig.node.json",
 		"check:pack": "publint && attw --pack . --profile esm-only",
 		"test": "vitest",
 		"test:run": "vitest run --reporter=verbose",
@@ -95,11 +91,14 @@
 		"demo:todo": "vite --config demo/todo_mvc/vite.config.ts",
 		"demo:todo:build": "tsx demo/build-demo.ts todo_mvc",
 		"demo:todo:serve": "vite preview --outDir public/todo_mvc --port 5175 --host",
+		"demo:docs": "vite --config demo/docs/vite.config.ts",
+		"demo:docs:build": "tsx demo/docs/vite.docs.bundle.ts",
+		"demo:docs:serve": "vite preview --outDir public --port 5176 --host",
 		"typedoc": "typedoc --displayBasePath ./typedoc/",
 		"bundle": "tsx vite.build.ts",
 		"clean": "rm -rf dist public build coverage",
-		"build": "pnpm run clean && tsc -p tsconfig.lib.json && tsc -p tsconfig.cli.json && chmod +x dist/cli/index.js && pnpm run mcp:build && pnpm run test:coverage && pnpm run bundle && pnpm run check:pack && pnpm run typedoc && pnpm run demo:build && pnpm run demo:shop:build && pnpm run demo:todo:build && find src -name '*.js' -delete",
-		"mcp:build": "tsc -p tsconfig.mcp.json && node mcp-docs-generate.ts && cp -r docs/concepts dist/mcp/concepts && chmod +x dist/mcp/index.js",
+		"build": "pnpm run clean && tsc --emitDeclarationOnly -p tsconfig.lib.json && tsc --emitDeclarationOnly -p tsconfig.cli.json && tsc --emitDeclarationOnly -p tsconfig.mcp.json && pnpm run bundle && chmod +x dist/cli/index.js dist/mcp/index.js && pnpm run mcp:docs && cp -r docs/concepts dist/mcp/concepts && pnpm run test:coverage && pnpm run check:pack && pnpm run typedoc && pnpm run demo:build && pnpm run demo:shop:build && pnpm run demo:todo:build && pnpm run demo:docs:build",
+		"mcp:build": "node mcp-docs-generate.ts && cp -r docs/concepts dist/mcp/concepts",
 		"demo:build": "tsx demo/web-test/vite.demo.ts",
 		"dev": "vite preview --outDir build/web-test --port 10000 --host",
 		"doc": "vite preview --outDir public/typedoc --port 11000 --host",