@twobirds/microcomponents 0.9.0 → 0.10.0

package/dist/core/elements.js

@@ -1,11 +1,1234 @@
+//#region src/utils/events.ts
+/**
+@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
+frontend microcomponents themselves — for that purpose, use the inherited methods
+( `.on()`, `.one()`, `.off()`, `.trigger()`) that exist when you extend `DC`.
+
+Import this module when you need to exchange information with microcomponents from outside
+the microcomponent system (e.g., vanilla JS, React via `useRef()`, or other frameworks).
+
+The core feature is the ability to explicitly control event flow direction when using {@link trigger}:
+- upward propagation to ancestor components ('u')
+- local dispatch only ('l') [default]
+- downward propagation to descendant components ('d').
+
+@example
+html:
+```html
+<div class="grandparent">
+<div class="parent">
+<div class="child">
+</div>
+</div>
+</div>
+```
+
+javascript:
+```javascript
+import { on, one, trigger, off } from '@twobirds/microcomponents/events';
+
+const grandParent = document.querySelector('.grandparent');
+const parent = document.querySelector('.parent');
+const child = document.querySelector('.child');
+if (!grandParent || !parent || !child) throw new Error('example markup missing');
+
+const grandParentHandler = on(grandParent, 'dataReady', (ev) => console.log(ev.detail.data));
+
+const parentHandler = on(parent, 'dataReady', (ev) => ev.detail.control.stop());
+
+trigger(child, 'dataReady', { value: 42 }, 'u');
+
+off(parent, 'dataReady', parentHandler);
+off(grandParent, 'dataReady', grandParentHandler);
+```
+
+The `dataReady` event bubbles upward from the innermost `div`, but `parentHandler`
+calls `ev.detail.control.stop()`, so the `grandParent` handler is never reached.
+Handlers are detached with `off()` once they are no longer needed.
+*/
+/**
+* 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}.
+
+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);
+```
+@group Events
+*/
+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.
+
+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);
+});
+off(myElement, 'update', handler);
+```
+@group Events
+*/
+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.
+
+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));
+```
+
+The listener fires only once and detaches automatically.
+@group Events
+*/
+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();
+* }
+* ```
+*/
+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.
+*/
+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
+//#region src/utils/helpers.ts
+/**
+* Converts a kebab-case string to PascalCase.
+* Example: 'my-component-name' -> 'MyComponentName'
+* @param str - The kebab-case string to convert.
+* @returns The converted PascalCase string.
+*
+* @example
+* ```ts
+* console.log(kebabToPascal('my-element'));
+* ```
+*/
+function kebabToPascal(str) {
+	return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+/**
+* 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}\``
+*/
+var _injectedCSS = /* @__PURE__ */ new WeakMap();
+function injectCSS(target, css) {
+	const injected = _injectedCSS.get(target) ?? /* @__PURE__ */ new Set();
+	if (injected.has(css)) return target.adoptedStyleSheets[0];
+	injected.add(css);
+	_injectedCSS.set(target, injected);
+	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 instance - The micro component 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>'
+* });
+* ```
+*/
+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;
+* });
+* ```
+*/
+function loadAssets(name, assets) {
+	const parseAsset = (asset) => {
+		const m = asset.match(/^([a-z]+)([A-Z][a-z]*)$/);
+		if (m) return `./${name.replace(/-/g, "/")}.${m[1]}.${m[2].toLowerCase()}`;
+		return `./${name.replace(/-/g, "/")}.${asset.toLowerCase()}`;
+	};
+	return Promise.all(assets.map(async (asset) => {
+		const filename = parseAsset(asset);
+		try {
+			const resp = await fetch(filename);
+			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 {
+			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 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|{"action":"go"}'>Submit</button>
+* <input change="|cart-form|refresh">
+* ```
+*/
+function bindTemplateEvents(rootElement, instance) {
+	const allElements = [...rootElement.querySelectorAll("*")];
+	for (const el of allElements) {
+		if (!(el instanceof HTMLElement)) continue;
+		const attrs = [...el.attributes];
+		for (const attr of attrs) {
+			const lowerName = attr.name.toLowerCase();
+			if (!("on" + lowerName in el)) continue;
+			const parts = attr.value.trim().split("|");
+			if (parts.length < 2) continue;
+			const [selector, event, payload] = parts;
+			el.removeAttribute(attr.name);
+			let payloadData;
+			if (payload) try {
+				payloadData = JSON.parse(payload);
+			} catch {
+				payloadData = payload;
+			}
+			if (selector === "this" || selector === "") on(el, lowerName, () => instance.trigger(event, payloadData));
+			else on(el, lowerName, () => trigger(selector, event, payloadData));
+		}
+	}
+}
+//#endregion
+//#region src/core/mcGuards.ts
+function isMcHost(element, key) {
+	return typeof HTMLElement !== "undefined" && element instanceof HTMLElement && "_mc" in element && (key === void 0 || key in element._mc);
+}
+//#endregion
+//#region src/core/MC.ts
+function add(targetHTMLElement, key, element = {}) {
+	const node = targetHTMLElement;
+	if (!("_mc" in targetHTMLElement)) node._mc = new DC(targetHTMLElement);
+	const _mc = node._mc;
+	if (key.length && !_mc[key]) {
+		_mc[key] = element;
+		if (targetHTMLElement instanceof HTMLElement && !targetHTMLElement.getAttribute("data-mc")) targetHTMLElement.setAttribute("data-mc", "");
+	}
+	return node;
+}
+/**
+Removes a named microcomponent from the internal `_mc` collection of a target DOM node.
+
+This function deletes the specified key from the element's `_mc` hash object and, if the
+collection becomes empty, removes the `data-mc` attribute from the DOM node.
+
+The bare poisoned value (`el._mc.gone` without member access) is `never`,
+which is assignable to anything — only member/method use of a removed entry is caught.
+
+@template T - A plain or already-enhanced element type.
+@template K - The literal registration key; its entry is poisoned in the registry type.
+@param target - The DOM element whose microcomponent should be removed.
+@param key - The property name/key corresponding to the microcomponent to remove.
+*/
+function remove(target, key) {
+	if (!key) return;
+	const _mc = target._mc;
+	if (!_mc) return;
+	if (_mc[key]) delete _mc[key];
+	if (!Object.keys(_mc).length && target instanceof HTMLElement && target.hasAttribute("data-mc")) target.removeAttribute("data-mc");
+}
+/**
+Runs the "Init" lifecycle event on a DOM microcomponent instance asynchronously.
+
+This function schedules the `trigger('Init')` call in a microtask, ensuring
+that all synchronous initialization is complete before the lifecycle hook
+executes. Only `DC` instances have an Init lifecycle — the `McBase`
+constructor calls this exclusively behind an `instanceof DC` check, so the
+signature encodes that invariant instead of re-checking it at runtime.
+
+@param element - The DOM microcomponent instance on which to trigger the Init event.
+*/
+function init(element) {
+	queueMicrotask(() => {
+		element.trigger("Init", null);
+	});
+}
+/**
+Attaches event listeners to DOM elements based on method naming conventions.
+
+Scans the prototype of the provided element and attaches listeners for methods
+prefixed with `on` or `one`, corresponding to either native HTML events (e.g.,
+'onclick') or microcomponent-prefixed custom events (e.g., '_mcUpdate').
+
+@param element - The instance whose prototype should be scanned for event handlers.
+*/
+function autoAttachListeners(element) {
+	const sourceTarget = element.target;
+	const prototype = Object.getPrototypeOf(element);
+	const sourceElement = element;
+	const definedEventHandlerNames = Object.getOwnPropertyNames(prototype).filter((key) => /^(on[A-Z]|one[A-Z])/.test(key) && typeof prototype[key] === "function");
+	for (const eventHandlerName of definedEventHandlerNames) {
+		const once = /^one/.test(eventHandlerName);
+		const eventName = eventHandlerName.replace(/^one?/, "");
+		const listener = (ev) => sourceElement[eventHandlerName](ev);
+		on(sourceTarget, eventName, listener, once);
+	}
+}
+/**
+Retrieves immediate child microcomponents of a DOM node.
+
+Queries the DOM for descendant elements marked with `data-mc` that are direct
+children of the provided element and returns their associated `_mc` instances.
+
+@param domNode - The DOM element whose child microcomponents to find.
+@returns An array of child microcomponent instances.
+*/
+function getMcChildNodes(domNode) {
+	return Array.from(domNode.querySelectorAll("[data-mc]:not(:scope [data-mc] [data-mc])")).filter((e) => e instanceof HTMLElement && "_mc" in e).map((e) => e._mc);
+}
+/**
+Walks up the DOM from `from`, returning the `_mc` controller of the nearest
+`data-mc` ancestor — restricted, when `key` is given, to hosts whose registry
+actually carries that key. Hosts marked `data-mc` but not (yet) carrying an
+`_mc` record (e.g. autoload pending) are skipped rather than returned.
+
+@param from - The element whose ancestors to search (exclusive).
+@param key - Optional registry key the ancestor's `_mc` must contain.
+@returns The nearest matching controller, or null.
+*/
+function findMcAncestor(from, key) {
+	let el = from.parentElement?.closest("[data-mc]");
+	while (el instanceof HTMLElement) {
+		/* v8 ignore next */
+		if ("_mc" in el) {
+			const mc = el._mc;
+			if (key === void 0 || key in mc) return mc;
+		}
+		el = el.parentElement?.closest("[data-mc]");
+	}
+	return null;
+}
+/**
+The base class for all microcomponents — shared root of both {@link MC} and {@link DC}.
+
+Holds a `WeakRef` to the target (a DOM element for `DC`, or any plain object for `MC`)
+to avoid circular references. For `DC` subclasses it also bootstraps two automatic
+behaviours:
+
+1. **Event listener auto-attachment** — methods whose names start with `on` or `one`
+(e.g. `onClick`, `oneInit`) are wired to the target element via {@link on} / {@link one}.
+2. **"Init" lifecycle event** — dispatched asynchronously in a microtask so that all
+synchronous constructor work finishes first.
+
+Both mechanisms run only when the instance is a `DC` (checked with `instanceof DC`).
+Plain `MC` instances skip them entirely, keeping server-side usage lightweight.
+
+### Plugin extension points
+
+The prototype of `McBase` is the attachment point for optional plugins that curry
+additional instance methods onto every microcomponent. Two built-in plugins modify
+this class at runtime:
+
+- **{@link State.observePlugin}** — adds `notify()`, `subscribe()`, and `bind()` so that
+observable properties can be controlled directly on the component instance with
+fluent chaining. Call `observePlugin(DC)` once at module level to activate.
+
+- **{@link State.formValuePlugin}** — adds `formValues()` for two-way binding between DOM
+form controls and an observable property. Also pulls in all methods from
+{@link State.observePlugin}, so you can chain `.subscribe()` and `.bind()` after
+`.formValues()`. Call `formValuePlugin(DC)` once at module level to activate.
+
+Both plugins are idempotent — calling them multiple times has no side effects. They
+work by assigning methods onto `McBase.prototype` (reached via
+`Object.getPrototypeOf(Class.prototype)`) and use TypeScript module augmentation
+(`declare module`) so the added signatures appear in type-checking automatically.
+
+@template TTarget - The concrete type of the wrapped target; preserved by the
+{@link McBase.target} getter.
+
+@example Extending with plugins at runtime
+
+```ts
+import { DC, observePlugin, formValuePlugin } from '@twobirds/microcomponents';
+
+observePlugin(DC);
+formValuePlugin(DC);
+
+class MyForm extends DC {
+data = { name: '' };
+
+oneInit() {
+this
+.formValues(this.target, 'data')
+.subscribe('data', (v) => console.log(v))
+.bind('data', this.target);
+}
+}
+```
+
+`observePlugin(DC)` adds `notify()`, `subscribe()`, `bind()` to `McBase.prototype`;
+`formValuePlugin(DC)` adds `formValues()` and re-runs `observePlugin`. `oneInit()`
+runs once after the constructor.
+@group Micro Components
+*/
+var McBase = class {
+	_target;
+	/**
+	The constructor for the base `McBase` class.
+	
+	Initializes a weak reference to the target and triggers auto-attachment
+	of listeners and initialization lifecycle events.
+	
+	@param target - The object or element this microcomponent represents.
+	*/
+	constructor(target) {
+		this._target = new WeakRef(target || {});
+		if (this instanceof DC && this.constructor !== DC) {
+			autoAttachListeners(this);
+			const tag = this.constructor.tag;
+			if (tag === void 0 || tag.toUpperCase() === this.target.tagName) init(this);
+		}
+	}
+	/**
+	Returns the current target object (DOM node or other data) referenced by this microcomponent.
+	
+	Uses a `WeakRef` internally to avoid circular references, and safely dereferences it here.
+	
+	The dereference is asserted non-null: the controller is stored on its target
+	(`element._mc`), so any code that can reach the controller through the element is
+	holding the target alive. Only a controller retained independently after its element
+	was garbage-collected could observe a stale reference — do not cache controllers
+	detached from their elements.
+	
+	@returns The target object.
+	*/
+	get target() {
+		return this._target.deref();
+	}
+};
+/**
+@class DC
+---
+
+A DOM-centric microcomponent that operates on a specific HTML element.
+
+Extends {@link McBase} and associates itself with an actual DOM node via the
+`_target` reference. Provides methods for event handling, DOM traversal,
+and interaction with sibling or ancestor microcomponents.
+
+---
+
+## Static Configuration Properties
+
+DC classes support three static properties that configure custom elements
+before any instance is constructed:
+
+### `static tag?: string`
+
+Replaces the default target element with a semantic HTML element, or removes it entirely.
+
+- **Non-empty string** (e.g., `'header'`) — the original custom element is replaced
+with the specified built-in element. The original tag name is added as a CSS class.
+- **Empty string `''`** — the target element is removed from the DOM entirely.
+Useful for components that only inject global styles or act as style containers.
+
+@example static tag — replace with semantic element
+
+```ts
+class ShopHeader extends DC {
+static tag = 'header';
+}
+defineCE('shop-header', ShopHeader);
+```
+
+Produces `<header class="shop-header">` instead of `<shop-header>`.
+
+@example static tag — remove element entirely
+
+```ts
+class GlobalStyles extends DC {
+static tag = '';
+}
+defineCE('global-styles', GlobalStyles);
+```
+
+The element self-destructs; only side effects (e.g., injected styles) remain.
+
+### `static assets: string[]`
+
+Declares companion files for auto-loading by convention. Asset names are camelCase
+and translated into file extensions: `'targetHtml'` → `.target.html`, `'json'` → `.json`.
+
+The path is derived from the custom element tag segments, and the basename is the
+last segment. For `<cart-container-checkout>`, assets load from `/cart/container/checkout.*`.
+
+When assets finish loading, an `'assets'` event fires so that `oneAssets(ev)` can
+process them. Everything ending in `Json` arrives parsed; all other files arrive as text.
+
+**One-time global styles**: Assets named `'css'` and `'targetCss'` inject CSS into the
+global document scope via `injectCSS(document, ...)`. Because these are idempotent
+global side effects, they are processed only once — after the first instance loads them,
+the entries are removed from both `static assets` and `static _assets`. Subsequent
+instances skip loading and re-processing them entirely.
+
+**CSS file roles**:
+
+- `.css` — design tokens only (CSS custom-property presets). Injected into the document
+scope once, like `targetCss`.
+- `.target.css` — layout rules for the light DOM. Also document-scoped and one-time.
+- `.shadow.css` — layout rules for the shadow DOM. Injected per instance into the
+component's own shadow root, so each instance gets its own copy.
+
+Every declared asset — CSS, HTML, JSON — is inlined into `static _assets` at build time by
+the load-assets plugin, so a bundled build performs no fetches at all.
+
+In a bundled build the plain `.css` files are additionally concatenated into a single
+`bundle.css` by the bundling script. That file is a convenience listing of the available
+variables: copy the ones you want to change into your own stylesheet and override them
+there. It is not required at runtime, and it cannot drift from the inlined presets — both
+are read from the same source files.
+
+The runtime decides whether an asset still needs fetching with `!ctor._assets[key]`, so an
+inlined entry must never be an empty string: that would trigger a re-fetch of a file that
+does not exist in a bundled build.
+
+@example static assets with autoload
+
+```ts
+class CartCheckout extends DC {
+static assets = ['targetHtml', 'targetCss', 'configJson'];
+
+oneAssets(ev) {
+const { configJson } = ev.detail.data;
+console.log(configJson);
+}
+}
+defineCE('cart-checkout', CartCheckout);
+```
+
+`configJson` arrives already parsed into an object.
+
+### `static attributes?: object`
+
+Sets HTML attributes on every instance automatically.
+
+@example static attributes
+
+```ts
+class ProductCard extends DC {
+static attributes = { role: 'listitem' };
+}
+defineCE('product-card', ProductCard);
+```
+
+Every `<product-card>` carries `role="listitem"`.
+
+### Combined usage
+
+All three can be combined in one class:
+
+@example All static properties together
+
+```ts
+class ShopCatalog extends DC {
+static tag = 'section';
+static attributes = { role: 'list', 'aria-label': 'products' };
+static assets = ['targetHtml', 'targetCss'];
+}
+defineCE('shop-catalog', ShopCatalog);
+```
+
+Produces `<section role="list" aria-label="products">`.
+
+---
+
+## Event Handler Conventions
+
+Methods whose names start with `on` or `one` are automatically wired as event listeners
+on the target element. The prefix determines persistence:
+
+- **`on<EventName>`** — persistent listener (fires every time)
+- **`one<EventName>`** — one-time listener (fires once, then detaches)
+
+### Web Component Lifecycle Events
+
+When a DC is registered via {@link defineCE}, the custom element dispatches these
+internal events that can be caught with handler methods:
+
+| Method | When it fires |
+|--------|---------------|
+| `onConnected()` | Element was inserted into the DOM (`connectedCallback`) |
+| `onDisconnected()` | Element was removed from the DOM (`disconnectedCallback`) |
+| `onAdopted()` | Element was moved to a new document (`adoptedCallback`) |
+| `onAttributeChanged()` | An observed attribute changed (`attributeChangedCallback`) |
+| `oneInit()` | Constructor finished; all synchronous setup complete (microtask) |
+| `oneAssets()` | Constructor finished; all assets loaded and available; ev contains assets object |
+
+@example Event handlers in action
+
+```ts
+class MyElement extends DC {
+onConnected() {
+console.log('entered the DOM');
+}
+
+onDisconnected() {
+console.log('left the DOM');
+}
+
+onClick() {
+this.trigger('something', 'payload');
+}
+
+oneSomething(ev) {
+console.log('first time only:', ev.detail.data);
+}
+}
+defineCE('my-element', MyElement);
+```
+
+---
+
+## Construction Patterns
+
+### Template usage (declarative)
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+```
+
+The registered element is then used in HTML as `<my-element></my-element>`.
+
+### Programmatic construction with data
+
+When constructing programmatically via {@link getCE}, pass only the `data` payload —
+the target element is created automatically by the custom element constructor.
+
+@example Programmatic construction
+
+```ts
+class MyElement extends DC {
+data = {};
+
+constructor(target, data) {
+super(target);
+this.data = data;
+}
+}
+defineCE('my-element', MyElement);
+
+const Ctor = getCE('my-element');
+document.body.append(new Ctor({ name: 'John' }));
+```
+
+### Data from HTML attributes
+
+@example Reading data from an attribute
+
+```ts
+class MyElement extends DC {
+data = {};
+
+constructor(target) {
+super(target);
+this.data = JSON.parse(target.getAttribute('my-data'));
+}
+}
+defineCE('my-element', MyElement);
+```
+
+Used in HTML as `<my-element my-data='{"name":"John"}'></my-element>`.
+
+---
+
+## Plugin Extension Points
+
+The prototype of `DC` (inherited from {@link McBase}) is extended at runtime by optional
+plugins. See the {@link McBase} documentation for details on {@link State.observePlugin} and
+{@link State.formValuePlugin}.
+
+@template T - The concrete element type of the host element.
+@template EM - The component's custom event map (`event name → payload type`).
+Declaring it registers events on the type level: `trigger()` enforces the
+payload for registered names, and `on()`/`one()` handlers receive
+`CustomEvent<McDetail<Payload>>` with no annotation needed. Unregistered
+names keep the open `unknown`-payload behavior.
+
+@example Typed event map
+
+```ts
+class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {
+checkout() {
+this.trigger('CartUpdate', { count: 2 }, 'u');
+this.on('CartUpdate', (ev) => ev.detail.data.count);
+}
+}
+```
+
+`trigger()` checks the payload against the registered `CartUpdate` shape, and the `on()`
+handler receives a fully typed `ev`.
+@group Micro Components
+*/
+var DC = class DC extends McBase {
+	/**
+	* Replaces the target element with a semantic HTML tag, or removes it entirely.
+	* Set to `'header'` to swap `<my-element>` for `<header>`, or `''` to self-destruct.
+	*/
+	static tag;
+	/**
+	* Result container for assets (e.g., `['targetHtml', 'json']`).
+	* Asset names (keys) are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
+	*/
+	static _assets = {};
+	/**
+	* Declares companion files for auto-loading by convention (e.g., `['targetHtml', 'json']`).
+	* Asset names are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
+	*/
+	static assets = [];
+	/**
+	* In-flight asset request, cached per class so that instances constructed while
+	* the first fetch is still pending (e.g. in a loop) share a single request
+	* instead of each triggering their own. Resolves to the freshly loaded assets.
+	*/
+	static _assetsPromise;
+	/**
+	* Sets HTML attributes on every instance automatically.
+	* Example: `{ role: 'listitem', 'aria-label': 'nav' }`.
+	*/
+	static attributes = {};
+	/**
+	* Constructs a new DC instance and applies static configuration.
+	*
+	* The constructor performs these steps in order:
+	* 1. Calls {@link McBase} to establish the target reference and auto-attach listeners.
+	* 2. If `static tag` is set and differs from the current element, replaces the target
+	*    with a new built-in element (or removes it if `tag === ''`).
+	* 3. If `static assets` has entries, initiates asynchronous loading, fires an `'assets'` event when complete handled by `oneAssets(ev)`.
+	* 4. Applies any `static attributes` to the target element.
+	*
+	* @param target - The host DOM element this component operates on.
+	*/
+	constructor(target) {
+		super(target);
+		const ctor = this.constructor;
+		if (ctor === DC) return;
+		const tagName = this.target.tagName.toLowerCase();
+		if (ctor["tag"] !== void 0 && tagName !== ctor.tag && ctor.tag !== "") {
+			const element = document.createElement(ctor.tag);
+			element.classList.add(tagName);
+			ctor._originalTag = tagName;
+			DC.add(element, ctor.name, new ctor(element));
+			delete ctor._originalTag;
+			if (tagName.includes("-") && !this.target.isConnected) this.on("connected", () => this.target.replaceWith(element));
+			else this.target.replaceWith(element);
+			return;
+		}
+		const attributes = ctor.attributes;
+		if (ctor.attributes) Object.keys(ctor.attributes).forEach((key) => {
+			this.target.setAttribute(key, attributes[key]);
+		});
+		const that = this;
+		const remainingAssets = ctor.assets.filter((key) => !ctor._assets[key]);
+		if (Object.keys(ctor._assets).length) processAssets(this, ctor._assets);
+		if (remainingAssets.length) {
+			if (!ctor._assetsPromise) ctor._assetsPromise = loadAssets(ctor._originalTag || tagName, remainingAssets).then((res) => {
+				const loadedAssets = {};
+				remainingAssets.forEach((key, i) => {
+					loadedAssets[key] = res[i];
+				});
+				ctor._assets = Object.assign({}, ctor._assets, loadedAssets);
+				for (const onceKey of ["css", "targetCss"]) if (loadedAssets[onceKey] !== void 0) delete ctor._assets[onceKey];
+				ctor.assets = ctor.assets.filter((key) => key !== "css" && key !== "targetCss");
+				return loadedAssets;
+			});
+			ctor._assetsPromise.then((loadedAssets) => {
+				processAssets(this, loadedAssets);
+				that.trigger("assets", ctor._assets);
+			});
+		} else if ([...Object.keys(ctor._assets)].length) queueMicrotask(() => that.trigger("assets", ctor._assets));
+		if (ctor.tag === "") {
+			this.target.remove();
+			return;
+		}
+	}
+	/**
+	Returns the loaded assets for this component instance.
+	
+	Assets are loaded asynchronously when `static assets` is defined on the class.
+	This method returns the resolved asset map keyed by filename, or `undefined`
+	if assets have not yet been loaded.
+	
+	@returns A record mapping asset keys to their content strings, or undefined.
+	*/
+	getAssets() {
+		return this.constructor._assets || {};
+	}
+	/**
+	Static helper to attach a microcomponent instance to a DOM element.
+	
+	Wrapper around the `add()` utility function, providing a class-level API
+	for adding child microcomponents to a target node.
+	
+	@template T - The concrete element type of the target; preserved in the return type.
+	@template K - The literal registration key; becomes a known entry of the returned `_mc` registry.
+	@template E - The type of the attached element; retrievable as `result._mc[key]`.
+	@param target - The DOM element to which to attach the microcomponent.
+	@param key - The property name/key under which to store the instance in `_mc`.
+	@returns The target DOM element with the attached microcomponent.
+	*/
+	static add(target, key, element = {}) {
+		return add(target, key, element);
+	}
+	/**
+	Static helper to remove a named microcomponent from a DOM element.
+	
+	Wrapper around the `remove()` utility function, providing a class-level API
+	for removing child microcomponents.
+	
+	@template T - A plain or already-enhanced element type.
+	@template K - The literal registration key; its entry is poisoned in the registry type.
+	@param target - The DOM element from which to remove the microcomponent.
+	@param key - The property name/key corresponding to the microcomponent to remove.
+	*/
+	static remove(target, key) {
+		remove(target, key);
+	}
+	/**
+	Class-verified entry lookup: returns the component stored under `key` on the
+	element's `_mc` record — but only if it is an instance of `Klass`.
+	
+	This is the *sound* retrieval primitive: presence AND type identity are both
+	proven at runtime (`instanceof`), so it needs no global `McRegistry`
+	declaration and stays correct even when different elements use the same key
+	name for different component types. Accepts any value (including
+	`querySelector` results that may be null) — every failure mode returns
+	`undefined`.
+	
+	@template E - The component type, inferred from `Klass`.
+	@param element - The value to look the entry up on; anything non-host yields undefined.
+	@param key - The registry key name to look under.
+	@param elementMcClass - The class the entry must be an instance of.
+	@returns The verified instance, or undefined.
+	@example
+	```ts
+	const cart = DC.get(document.querySelector('form'), 'cart', Cart);
+	cart?.addItem(item);
+	```
+	
+	`cart` is `Cart | undefined` — presence and type identity are both proven by the
+	`instanceof` check inside `get()`, with no global declaration involved.
+	*/
+	static get(element, key, elementMcClass) {
+		if (!isMcHost(element)) return void 0;
+		const entry = element._mc[key];
+		return entry instanceof elementMcClass ? entry : void 0;
+	}
+	/**
+	Detaches an event listener from the DOM node.
+	
+	This is an instance method wrapper for `off()`, using the internal `_target` DOM reference.
+	
+	@param eventName - The name of the event (e.g., 'click', 'update').
+	@param handler - The previously attached callback function or object to remove.
+	*/
+	off(eventName, handler) {
+		off(this.target, eventName, handler);
+	}
+	/**
+	Attaches a persistent event listener to the DOM node.
+	
+	This is an instance method wrapper for `on()`, using the internal `_target` DOM reference.
+	
+	The handler receives a `CustomEvent<McDetail<Payload>>`. For event names
+	registered in the component's event map `EM` the payload is resolved from the
+	map — an unannotated arrow handler is fully typed. For unregistered names the
+	payload defaults to `unknown` and can be pinned via the type argument
+	(`on<Payload>('Name', handler)`) or the handler's own annotation.
+	
+	@param eventName - The name of the event (e.g., 'click', 'update').
+	@param handler - The callback function or object to invoke.
+	@returns The attached handler reference, unchanged — usable directly with {@link off}.
+	*/
+	on(eventName, handler) {
+		return on(this.target, eventName, handler);
+	}
+	/**
+	Attaches a one-time event listener to the DOM node.
+	
+	This is an instance method wrapper for `one()`, using the internal `_target` DOM reference.
+	Payload typing follows the same rules as {@link DC.on}.
+	
+	@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, unchanged — usable directly with {@link off}.
+	*/
+	one(eventName, handler) {
+		return one(this.target, eventName, handler);
+	}
+	/**
+	Triggers a custom event on the DOM node and optionally bubbles it.
+	
+	This is an instance method wrapper for `trigger()`, using the internal `_target` DOM reference.
+	
+	For event names registered in the component's event map `EM` the payload type
+	is enforced; unregistered names accept any payload (typed via inference or an
+	explicit `trigger<Payload>(...)` argument).
+	
+	@param eventName - 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.
+	*/
+	trigger(eventName, data = {}, bubble = "l", controller) {
+		trigger(this.target, eventName, data, bubble, controller);
+	}
+	/**
+	Returns an array of all ancestor microcomponents up the DOM tree.
+	
+	Traverses upward from this element's target, collecting the `_mc` instances
+	of ancestor elements marked with `data-mc`. The keyed form only collects
+	hosts whose registry carries `key`, typed from the global {@link McRegistry}
+	binding — non-optional, since presence is checked during the walk.
+	
+	@template R - Known registry entries of the results; pass a record to assert
+	a site-specific shape: `ancestors<{ cart: Cart }>()`. Defaults to none.
+	@returns An array of ancestor microcomponent instances (empty if none found).
+	*/
+	ancestors(key) {
+		const result = [];
+		let current = findMcAncestor(this.target, key);
+		while (current) {
+			result.push(current);
+			current = findMcAncestor(current.target, key);
+		}
+		return result;
+	}
+	/**
+	Returns the closest ancestor microcomponent or null if none found.
+	
+	This method is equivalent to calling `ancestors()[0]`, but more concise.
+	The keyed form walks up to the nearest host whose registry carries `key`,
+	typed from the global {@link McRegistry} binding — non-optional, since
+	presence is checked during the walk.
+	
+	@template R - Known registry entries of the result; pass a record to assert
+	a site-specific shape: `closest<{ cart: Cart }>()?.cart.addItem(...)`.
+	Defaults to none.
+	@returns The nearest matching ancestor's `_mc`, or null if not found.
+	*/
+	closest(key) {
+		return findMcAncestor(this.target, key);
+	}
+	/**
+	Returns an array of direct child microcomponents.
+	
+	Calls `getMcChildNodes()` internally to find immediate descendants only,
+	excluding nested grandchildren and deeper levels. The keyed form filters to
+	hosts whose registry carries `key`; see {@link DC.closest}.
+	
+	@template R - Known registry entries of the results; see {@link DC.closest}.
+	@returns An array of child microcomponent instances (empty if none found).
+	*/
+	children(key) {
+		const kids = getMcChildNodes(this.target);
+		return key === void 0 ? kids : kids.filter((mc) => key in mc);
+	}
+	/**
+	Returns an array of all descendant microcomponents recursively.
+	
+	Uses a `querySelectorAll` query to collect every nested element marked with
+	`data-mc`, returning their associated `_mc` instances. The keyed form
+	filters to hosts whose registry carries `key`; see {@link DC.closest}.
+	
+	@template R - Known registry entries of the results; see {@link DC.closest}.
+	@returns An array of descendant microcomponent instances (empty if none found).
+	*/
+	descendants(key) {
+		return Array.from(this.target.querySelectorAll("[data-mc]")).filter((e) => e instanceof HTMLElement && "_mc" in e).map((e) => e._mc).filter((mc) => key === void 0 || key in mc);
+	}
+};
+//#endregion
+//#region src/core/elements.ts
 /**
 Custom element registration utilities — bridges DC microcomponents with the native
 `CustomElementRegistry`.
 
 This module provides:
 - {@link defineCE} — wraps `customElements.define()` to register a custom element that
-  hosts a DC instance in its `_mc` registry. The defining class also controls observed
-  attributes; all inner MCs receive lifecycle events (`connected`, `disconnected`, etc.).
+hosts a DC instance in its `_mc` registry. The defining class also controls observed
+attributes; all inner MCs receive lifecycle events (`connected`, `disconnected`, etc.).
 - {@link getCE} — typed wrapper for `customElements.get()`.
 - {@link listCE} — returns every tag name registered via {@link defineCE}.
 
@@ -30,11 +1253,11 @@ The registered element is then used in HTML as `<my-element></my-element>`.
 ```ts
 const MyElementClass = getCE('my-element');
 if (MyElementClass) {
-    document.body.append(new MyElementClass());
+document.body.append(new MyElementClass());
 }
 ```
 
-@example List all custom element tags registered by defineCE
+@example List all custom element tags registered by defineCE 
 
 ```ts
 defineCE('my-element', MyElement);
@@ -42,8 +1265,6 @@ defineCE('another-widget', AnotherWidget);
 console.log(listCE());
 ```
 */
-import { kebabToPascal } from '../utils/helpers.js';
-import { McBase, DC } from './MC.js';
 /**
 Creates a named class constructor with the specified name.
 @param name - The desired name for the class.
@@ -57,14 +1278,14 @@ console.log(MyNamedClass.name);
 ```
 */
 function createNamedClass(name, targetClass) {
-    return Object.defineProperty(targetClass, 'name', { value: name });
+	return Object.defineProperty(targetClass, "name", { value: name });
 }
 function Base(ElementClass) {
-    return class extends ElementClass {
-        constructor(...args) {
-            super(...args);
-        }
-    };
+	return class extends ElementClass {
+		constructor(...args) {
+			super(...args);
+		}
+	};
 }
 /**
 ### Examples
@@ -83,9 +1304,9 @@ The registered element is then used in HTML as `<my-element></my-element>`.
 
 ```ts
 class MyElement extends DC {
-    onAttributeChanged(ev){
-        const newValue = ev.detail.data.newValue;
-    }
+onAttributeChanged(ev){
+const newValue = ev.detail.data.newValue;
+}
 }
 defineCE('my-element', MyElement, ['observed']);
 ```
@@ -105,66 +1326,62 @@ the element instance with DC (DomComponent).
 @param observedAttributes - An optional array of attribute names to observe for changes.
 @param extend - DEPRECATED! An optional built-in HTML element tag name to extend, enabling customized built-in elements.
 @returns The registered custom element constructor, typed to accept the `data` payload
-    and exposing the `_mc` entry under the PascalCase tag name — or `undefined` if the
-    tag name was already defined. Feed it (or an equivalent `McElementConstructor`) to
-    the global {@link McElementTagNameMap} to make `getCE()` return it typed by string.
+and exposing the `_mc` entry under the PascalCase tag name — or `undefined` if the
+tag name was already defined. Feed it (or an equivalent `McElementConstructor`) to
+the global {@link McElementTagNameMap} to make `getCE()` return it typed by string.
 @group Elements
 */
-// Implementation signature (not directly callable)
-export function defineCE(tagName, DefinitionClass, observedAttributes = [], extend) {
-    if (customElements.get(tagName)) {
-        console.warn(`IGNORED: Custom element "${tagName}" is already defined!`);
-        return;
-    }
-    if (!tagName.includes('-')) {
-        throw new Error('createCustomElement: tagName must contain at least one hyphen ("-").');
-    }
-    let extendClass = HTMLElement;
-    if (extend) {
-        extendClass = document.createElement(extend).constructor;
-    }
-    const pascalCaseName = kebabToPascal(tagName);
-    // a class, but not a MC — the class itself is the element; no `._mc` is attached
-    if (!(DefinitionClass.prototype instanceof McBase)) {
-        customElements.define(tagName, DefinitionClass);
-        return DefinitionClass;
-    }
-    // a MC
-    const McElementClass = createNamedClass(pascalCaseName, class extends Base(extendClass) {
-        constructor(data) {
-            super();
-            DC.add(this, pascalCaseName, new DefinitionClass(this, data));
-        }
-        connectedCallback() {
-            this.dispatchEvent(new CustomEvent('_mcConnected'));
-        }
-        connectedMoveCallback() {
-            this.dispatchEvent(new CustomEvent('_mcConnectedMove'));
-        }
-        disconnectedCallback() {
-            this.dispatchEvent(new CustomEvent('_mcDisconnected'));
-        }
-        adoptedCallback() {
-            this.dispatchEvent(new CustomEvent('_mcAdopted'));
-        }
-        attributeChangedCallback(name, oldValue, newValue) {
-            this.dispatchEvent(new CustomEvent('_mcAttributeChanged', { detail: { name, oldValue, newValue } }));
-        }
-        formResetCallback() {
-            this.dispatchEvent(new CustomEvent('_mcFormReset'));
-        }
-        static get observedAttributes() {
-            return [...observedAttributes];
-        }
-    });
-    customElements.define(tagName, McElementClass, { extends: extend });
-    if (!defineCE.list)
-        defineCE.list = [];
-    defineCE.list.push(tagName);
-    return McElementClass;
-}
-export function getCE(tagName) {
-    return customElements.get(tagName);
+function defineCE(tagName, DefinitionClass, observedAttributes = [], extend) {
+	if (customElements.get(tagName)) {
+		console.warn(`IGNORED: Custom element "${tagName}" is already defined!`);
+		return;
+	}
+	if (!tagName.includes("-")) throw new Error("createCustomElement: tagName must contain at least one hyphen (\"-\").");
+	let extendClass = HTMLElement;
+	if (extend) extendClass = document.createElement(extend).constructor;
+	const pascalCaseName = kebabToPascal(tagName);
+	if (!(DefinitionClass.prototype instanceof McBase)) {
+		customElements.define(tagName, DefinitionClass);
+		return DefinitionClass;
+	}
+	const McElementClass = createNamedClass(pascalCaseName, class extends Base(extendClass) {
+		constructor(data) {
+			super();
+			DC.add(this, pascalCaseName, new DefinitionClass(this, data));
+		}
+		connectedCallback() {
+			this.dispatchEvent(new CustomEvent("_mcConnected"));
+		}
+		connectedMoveCallback() {
+			this.dispatchEvent(new CustomEvent("_mcConnectedMove"));
+		}
+		disconnectedCallback() {
+			this.dispatchEvent(new CustomEvent("_mcDisconnected"));
+		}
+		adoptedCallback() {
+			this.dispatchEvent(new CustomEvent("_mcAdopted"));
+		}
+		attributeChangedCallback(name, oldValue, newValue) {
+			this.dispatchEvent(new CustomEvent("_mcAttributeChanged", { detail: {
+				name,
+				oldValue,
+				newValue
+			} }));
+		}
+		formResetCallback() {
+			this.dispatchEvent(new CustomEvent("_mcFormReset"));
+		}
+		static get observedAttributes() {
+			return [...observedAttributes];
+		}
+	});
+	customElements.define(tagName, McElementClass, { extends: extend });
+	if (!defineCE.list) defineCE.list = [];
+	defineCE.list.push(tagName);
+	return McElementClass;
+}
+function getCE(tagName) {
+	return customElements.get(tagName);
 }
 /**
 Returns an array of all tag names registered via {@link defineCE}.
@@ -177,6 +1394,8 @@ console.log(listCE());
 ```
 @group Elements
 */
-export function listCE() {
-    return defineCE.list ?? [];
+function listCE() {
+	return defineCE.list ?? [];
 }
+//#endregion
+export { defineCE, getCE, listCE };