@twobirds/microcomponents 0.2.2 → 0.2.3

package/dist/core/elements.d.ts

@@ -1,218 +1,46 @@
 /**
- * # Custom Elements
- * ---
- * Defines micro component integration with native web components and the CustomElementRegistry.
- * This module provides utilities for defining custom HTML elements using the native Web Components API.
- *
- * ---
- * The {@link defineCE} function handles registration of custom elements with the CustomElementRegistry,
- * automatically attaching the provided class as a DC instance ( micro component ) to the native web component created.
- * This class and any DC instances added to the web component later will receive all web component native events.
- * Only the class that defines the WC also defines its observed attributes, but all inner DCs get the changed event.
- * The {@link getCE} function is just a wrapper for customElements.get()
- *
- * ## Hints:
- * - Your micro component must extend DC, since it is a DOM element
- * - Method names that look like event handlers are DOM - or custom event handlers ( 'onClick()', 'oneSomething()' )
- * - Event handlers defined as methods will be assigned to the DOM automatically
- * - Micro components trigger an `init` event on themself after the constructor has run. The method `.oneInit()` catches this lifecycle event.
- *
- * ---
- *
- * @module elements
- *
- * ## Examples:
- *
- * @example define a custom component, minimum code
- *
- * javascript:
- * ```javascript
- * class MyElement extends DC {
- * 	constructor( target ){
- * 		super(target);
- * 	}
- * }
- *
- * defineCE( 'my-element', MyElement );
- * ```
- *
- * afterwards you can use ...
- *
- * html:
- * ```HTML
- * <my-element></my-element>
- * ```
- * ... in your template.
- *
- * Or you can construct it programmatically using {@link getCE}:
- *
- * javascript:
- * ```javascript
- * const MyElementClass = getCE('my-element');
- * const body = document.body;
- * body.append( new MyElementClass() );
- * ```
- *
- * ---
- * @example define a custom component with standard and/or custom event handlers
- *
- * javascript:
- * ```javascript
- * class MyElement extends DC {
- *
- * 	constructor( target ){
- * 		super(target);
- * 	}
- *
- * 	// DOM web component event handler
- * 	onConnected() {
- * 		this.innerHTML = '<p>Hi!</p>';
- * 	}
- *
- * 	// DOM standard event handler
- * 	onClick(){
- * 		this.trigger('something', { data: 'do something' } );
- * 	}
- *
- * 	// DOM custom event handler
- * 	oneSomething(ev){
- * 		// do only once! Subsequent clicks will not trigger this handler
- * 		console.log('something happens here:', ev.detail.data );
- * 	}
- * }
- * defineCE( 'my-element', MyElement );
- * ```
- *
- * ## Static properties
- *
- * DC classes support some static properties that configure the custom element
- * before any instance is constructed. These are applied automatically by `defineCE`
- * during element creation.
- *
- * ---
- * @example static tag
- * - replaces the default `target` element with a semantic HTML element:
- *
- * html before:
- * ```html
- * <shop-header></shop-header>
- * ```
- * javascript:
- * ```javascript
- * class ShopHeader extends DC {
- * 	static tag = 'header';
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * }
- * defineCE('shop-header', ShopHeader);
- * ```
- *
- * html after:
- * ```html
- * <header></header>
- * ```
- *
- * The resulting DOM node is a `<header>` element instead of a generic template.
- *
- * ---
- * @example static assets
- * - declares companion files for auto-load and bundling by convention:
- *
- * javascript:
- * ```javascript
- * class CartContainerCheckout extends DC {
- * 	static assets = ['targetHtml', 'targetCss'];
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * 	oneAssets() {
- * 		this.setupBehaviour();
- * 	}
- * }
- * defineCE('cart-container-checkout', CartContainerCheckout);
- * ```
- *
- * The framework resolves `targetHtml` → `checkout.target.html` and
- * `targetCss` → `checkout.target.css`, injects them into the element, and fires
- * the `_mcAssets` event so that `oneAssets()` runs.
- *
- * ---
- * @example static attributes
- * - sets HTML attributes on every instance:
- *
- * javascript:
- * ```javascript
- * class ProductCard extends DC {
- * 	static attributes = { role: 'listitem' };
- * 	constructor(target, data) {
- * 		super(target);
- * 	}
- * }
- * defineCE('product-card', ProductCard);
- * ```
- *
- * Every `<product-card>` element carries the attribute `role="listitem"` automatically:
- *
- * html after:
- * ```html
- * <product-card role="listitem"></product-card>
- * ```
- *
- * ---
- * @example
- * - All three can be combined in one class:
- *
- * javascript:
- * ```javascript
- * class ShopCatalog extends DC {
- * 	static tag = 'section';
- * 	static attributes = { role: 'list', 'aria-label': 'products' };
- * 	static assets = ['targetHtml', 'targetCss'];
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * }
- * defineCE('shop-catalog', ShopCatalog);
- * ```
- *
- * Produces a `<section role="list" aria-label="products">` host element.
- *
- * ---
- * @example Creating a user defined built-in element (customized built-in element)
- * **Hint:**
- * - This is **DEPRECATED** in the standard. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#customized_built-in_elements). Use this only if you know what you are doing.
- * - This can be archieved in a safe way using the `static tag: 'aside';` property on your class.
- *
- * javascript:
- * ```javascript
- * class MyButton extends DC {
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * 	onConnected() {
- * 		this.textContent = 'Click me!';
- * 	}
- * }
- * defineCE('my-button', MyButton, [], 'button');
- * ```
- *
- * afterwards you can use it in your template with the `is` attribute:
- *
- * html:
- * ```html
- * <button is="my-button"></button>
- * ```
- *
- *
- * Or you can construct it programmatically using {@link getCE}:
- * javascript:
- * ```javascript
- * const MyButtonClass = getCE('my-button');
- * const body = document.body;
- * body.append( new MyButtonClass() );
- * ```
- */
+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.).
+- {@link getCE} — typed wrapper for `customElements.get()`.
+- {@link listCE} — returns every tag name registered via {@link defineCE}.
+
+Familiarity with the [Custom Elements Web Standard](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) is recommended.
+
+For DC-specific documentation (static properties, event handlers, lifecycle events,
+construction patterns), see the {@link DC} class in `MC.ts`.
+
+@group Elements
+
+@example Define custom element in registry
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+// Use in HTML: <my-element></my-element>
+```
+
+@example Retrieve custom element from registry
+
+```ts
+const MyElementClass = getCE('my-element');
+if (MyElementClass) {
+    document.body.append(new MyElementClass());
+}
+```
+
+@example List all custom element tags registered by defineCE
+
+```ts
+defineCE('my-element', MyElement);
+defineCE('another-widget', AnotherWidget);
+console.log(listCE()); // ['my-element', 'another-widget']
+```
+*/
 import { type McHost } from './MC.js';
 /**
 Resolves the host element type for a given `extend` tag: the matching built-in
@@ -224,12 +52,14 @@ plain `HTMLElement` otherwise.
 type Btn = TargetOf<'button'>; // HTMLButtonElement
 type Plain = TargetOf<'div'>;   // HTMLElement
 ```
+@group Types
 */
 export type TargetOf<E> = E extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[E] : HTMLElement;
 /**
 The type-level mirror of `kebabToPascal()` in helpers.ts: `'user-card'` →
 `'UserCard'`. Lets {@link defineCE} type the `_mc` registry entry under the
 exact key the runtime stores it at.
+@group Types
 */
 export type McPascalCase<S extends string> = S extends `${infer Head}-${infer Rest}` ? `${Capitalize<Head>}${McPascalCase<Rest>}` : Capitalize<S>;
 /**
@@ -243,6 +73,7 @@ name (`N`); with the default `N = string` no entry is claimed.
 @template D - The optional construction payload accepted by `new`.
 @template E - The built-in tag being extended, if any (customized built-in elements).
 @template N - The literal PascalCase registry key; `defineCE` fills in `McPascalCase<Tag>`.
+@group Types
 */
 export type McElementConstructor<T extends object = object, D = unknown, E extends keyof HTMLElementTagNameMap | undefined = undefined, N extends string = string> = new (data?: D) => McHost<TargetOf<E>, string extends N ? Record<never, never> : Record<N, T>>;
 declare global {
@@ -273,23 +104,6 @@ declare global {
     interface McElementTagNameMap {
     }
 }
-/**
-Defines a custom HTML element with optional observed attributes and micro component integration.
-The class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.
-Automatically assigns a "PascalCase" class name derived from the <kebab-case> tagName.
-If the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register
-the element instance with DC (DomComponent).
-
-@param tagName - The HTML tag name for the custom element (must contain at least one hyphen, enforced at compile time).
-@param DefinitionClass - The constructor function or class that defines the element's behavior. Its `target` parameter type follows `extend`; an optional second `data` parameter receives the payload passed on programmatic construction.
-@param observedAttributes - An optional array of attribute names to observe for changes.
-@param extend - 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.
-
-*/
 export declare function defineCE<Tag extends `${string}-${string}`, T extends object, D, E extends keyof HTMLElementTagNameMap | undefined = undefined>(tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data?: D) => T, observedAttributes?: string[], extend?: E): McElementConstructor<T, D, E, McPascalCase<Tag>> | undefined;
 export declare function defineCE<Tag extends `${string}-${string}`, T extends object, E extends keyof HTMLElementTagNameMap | undefined = undefined>(tagName: Tag, DefinitionClass: new (target: TargetOf<E>) => T, observedAttributes?: string[], extend?: E): McElementConstructor<T, undefined, E, McPascalCase<Tag>> | undefined;
 export declare function defineCE<Tag extends `${string}-${string}`, T extends object, D, E extends keyof HTMLElementTagNameMap | undefined = undefined>(tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data: D) => T, observedAttributes?: string[], extend?: E): McElementConstructor<T, D, E, McPascalCase<Tag>> | undefined;
@@ -312,7 +126,20 @@ if (MyElementClass) {
 
 @param tagName - The HTML tag name to look up.
 @returns The constructor if defined, or undefined if not found.
+@group Elements
 */
 export declare function getCE<K extends keyof McElementTagNameMap & string>(tagName: K): McElementTagNameMap[K] | undefined;
 export declare function getCE(tagName: string): CustomElementConstructor | undefined;
+/**
+Returns an array of all tag names registered via {@link defineCE}.
+
+@example
+```ts
+defineCE('my-element', MyElement);
+defineCE('another-widget', AnotherWidget);
+console.log(listCE()); // ['my-element', 'another-widget']
+```
+@group Elements
+*/
+export declare function listCE(): string[];
 //# sourceMappingURL=elements.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../src/core/elements.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../src/core/elements.ts"],"names":[],"mappings":"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"}

package/dist/core/elements.js

@@ -1,218 +1,46 @@
 /**
- * # Custom Elements
- * ---
- * Defines micro component integration with native web components and the CustomElementRegistry.
- * This module provides utilities for defining custom HTML elements using the native Web Components API.
- *
- * ---
- * The {@link defineCE} function handles registration of custom elements with the CustomElementRegistry,
- * automatically attaching the provided class as a DC instance ( micro component ) to the native web component created.
- * This class and any DC instances added to the web component later will receive all web component native events.
- * Only the class that defines the WC also defines its observed attributes, but all inner DCs get the changed event.
- * The {@link getCE} function is just a wrapper for customElements.get()
- *
- * ## Hints:
- * - Your micro component must extend DC, since it is a DOM element
- * - Method names that look like event handlers are DOM - or custom event handlers ( 'onClick()', 'oneSomething()' )
- * - Event handlers defined as methods will be assigned to the DOM automatically
- * - Micro components trigger an `init` event on themself after the constructor has run. The method `.oneInit()` catches this lifecycle event.
- *
- * ---
- *
- * @module elements
- *
- * ## Examples:
- *
- * @example define a custom component, minimum code
- *
- * javascript:
- * ```javascript
- * class MyElement extends DC {
- * 	constructor( target ){
- * 		super(target);
- * 	}
- * }
- *
- * defineCE( 'my-element', MyElement );
- * ```
- *
- * afterwards you can use ...
- *
- * html:
- * ```HTML
- * <my-element></my-element>
- * ```
- * ... in your template.
- *
- * Or you can construct it programmatically using {@link getCE}:
- *
- * javascript:
- * ```javascript
- * const MyElementClass = getCE('my-element');
- * const body = document.body;
- * body.append( new MyElementClass() );
- * ```
- *
- * ---
- * @example define a custom component with standard and/or custom event handlers
- *
- * javascript:
- * ```javascript
- * class MyElement extends DC {
- *
- * 	constructor( target ){
- * 		super(target);
- * 	}
- *
- * 	// DOM web component event handler
- * 	onConnected() {
- * 		this.innerHTML = '<p>Hi!</p>';
- * 	}
- *
- * 	// DOM standard event handler
- * 	onClick(){
- * 		this.trigger('something', { data: 'do something' } );
- * 	}
- *
- * 	// DOM custom event handler
- * 	oneSomething(ev){
- * 		// do only once! Subsequent clicks will not trigger this handler
- * 		console.log('something happens here:', ev.detail.data );
- * 	}
- * }
- * defineCE( 'my-element', MyElement );
- * ```
- *
- * ## Static properties
- *
- * DC classes support some static properties that configure the custom element
- * before any instance is constructed. These are applied automatically by `defineCE`
- * during element creation.
- *
- * ---
- * @example static tag
- * - replaces the default `target` element with a semantic HTML element:
- *
- * html before:
- * ```html
- * <shop-header></shop-header>
- * ```
- * javascript:
- * ```javascript
- * class ShopHeader extends DC {
- * 	static tag = 'header';
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * }
- * defineCE('shop-header', ShopHeader);
- * ```
- *
- * html after:
- * ```html
- * <header></header>
- * ```
- *
- * The resulting DOM node is a `<header>` element instead of a generic template.
- *
- * ---
- * @example static assets
- * - declares companion files for auto-load and bundling by convention:
- *
- * javascript:
- * ```javascript
- * class CartContainerCheckout extends DC {
- * 	static assets = ['targetHtml', 'targetCss'];
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * 	oneAssets() {
- * 		this.setupBehaviour();
- * 	}
- * }
- * defineCE('cart-container-checkout', CartContainerCheckout);
- * ```
- *
- * The framework resolves `targetHtml` → `checkout.target.html` and
- * `targetCss` → `checkout.target.css`, injects them into the element, and fires
- * the `_mcAssets` event so that `oneAssets()` runs.
- *
- * ---
- * @example static attributes
- * - sets HTML attributes on every instance:
- *
- * javascript:
- * ```javascript
- * class ProductCard extends DC {
- * 	static attributes = { role: 'listitem' };
- * 	constructor(target, data) {
- * 		super(target);
- * 	}
- * }
- * defineCE('product-card', ProductCard);
- * ```
- *
- * Every `<product-card>` element carries the attribute `role="listitem"` automatically:
- *
- * html after:
- * ```html
- * <product-card role="listitem"></product-card>
- * ```
- *
- * ---
- * @example
- * - All three can be combined in one class:
- *
- * javascript:
- * ```javascript
- * class ShopCatalog extends DC {
- * 	static tag = 'section';
- * 	static attributes = { role: 'list', 'aria-label': 'products' };
- * 	static assets = ['targetHtml', 'targetCss'];
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * }
- * defineCE('shop-catalog', ShopCatalog);
- * ```
- *
- * Produces a `<section role="list" aria-label="products">` host element.
- *
- * ---
- * @example Creating a user defined built-in element (customized built-in element)
- * **Hint:**
- * - This is **DEPRECATED** in the standard. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#customized_built-in_elements). Use this only if you know what you are doing.
- * - This can be archieved in a safe way using the `static tag: 'aside';` property on your class.
- *
- * javascript:
- * ```javascript
- * class MyButton extends DC {
- * 	constructor(target) {
- * 		super(target);
- * 	}
- * 	onConnected() {
- * 		this.textContent = 'Click me!';
- * 	}
- * }
- * defineCE('my-button', MyButton, [], 'button');
- * ```
- *
- * afterwards you can use it in your template with the `is` attribute:
- *
- * html:
- * ```html
- * <button is="my-button"></button>
- * ```
- *
- *
- * Or you can construct it programmatically using {@link getCE}:
- * javascript:
- * ```javascript
- * const MyButtonClass = getCE('my-button');
- * const body = document.body;
- * body.append( new MyButtonClass() );
- * ```
- */
+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.).
+- {@link getCE} — typed wrapper for `customElements.get()`.
+- {@link listCE} — returns every tag name registered via {@link defineCE}.
+
+Familiarity with the [Custom Elements Web Standard](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) is recommended.
+
+For DC-specific documentation (static properties, event handlers, lifecycle events,
+construction patterns), see the {@link DC} class in `MC.ts`.
+
+@group Elements
+
+@example Define custom element in registry
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+// Use in HTML: <my-element></my-element>
+```
+
+@example Retrieve custom element from registry
+
+```ts
+const MyElementClass = getCE('my-element');
+if (MyElementClass) {
+    document.body.append(new MyElementClass());
+}
+```
+
+@example List all custom element tags registered by defineCE
+
+```ts
+defineCE('my-element', MyElement);
+defineCE('another-widget', AnotherWidget);
+console.log(listCE()); // ['my-element', 'another-widget']
+```
+*/
 import { kebabToPascal } from '../utils/helpers.js';
 import { McBase, DC } from './MC.js';
 /**
@@ -237,6 +65,46 @@ function Base(ElementClass) {
         }
     };
 }
+/**
+### Examples
+---
+
+#### Define custom element in registry
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+// Use in HTML: <my-element></my-element>
+```
+#### Define custom element in registry with observed attributes
+
+```ts
+class MyElement extends DC {
+    onAttributeChanged(ev){
+        const newValue = ev.detail.data.newValue;
+    }
+}
+defineCE('my-element', MyElement, ['observed']);
+// Use in HTML: <my-element observed></my-element>
+// When the 'observed' attribut is changed, 'attributeChanged' is triggered, which in turn calls 'onAttributeChanged' with the data in the payload
+```
+
+Defines a custom HTML element with optional observed attributes and micro component integration.
+The class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.
+Automatically assigns a "PascalCase" class name derived from the <kebab-case> tagName.
+If the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register
+the element instance with DC (DomComponent).
+
+@param tagName - The HTML tag name for the custom element (must contain at least one hyphen, enforced at compile time).
+@param DefinitionClass - The constructor function or class that defines the element's behavior. Its `target` parameter type follows `extend`; an optional second `data` parameter receives the payload passed on programmatic construction.
+@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.
+@group Elements
+*/
 // Implementation signature (not directly callable)
 export function defineCE(tagName, DefinitionClass, observedAttributes = [], extend) {
     if (customElements.get(tagName)) {
@@ -285,8 +153,25 @@ export function defineCE(tagName, DefinitionClass, observedAttributes = [], exte
         }
     });
     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);
 }
+/**
+Returns an array of all tag names registered via {@link defineCE}.
+
+@example
+```ts
+defineCE('my-element', MyElement);
+defineCE('another-widget', AnotherWidget);
+console.log(listCE()); // ['my-element', 'another-widget']
+```
+@group Elements
+*/
+export function listCE() {
+    return defineCE.list ?? [];
+}