@twobirds/microcomponents 0.10.0 → 0.10.2

package/dist/state/formValues.js

@@ -399,6 +399,20 @@ function deepEqual(a, b) {
 	return true;
 }
 /**
+* Converts a PascalCase string to kebab-case.
+* Example: 'MyComponentName' -> 'my-component-name'
+* @param str - The PascalCase string to convert.
+* @returns The converted kebab-case string.
+*
+* @example
+* ```ts
+* console.log(pascalToKebab('MyElement'));
+* ```
+*/
+function pascalToKebab(str) {
+	return str.replace(/[A-Z]/g, (m, i) => (i ? "-" : "") + m.toLowerCase());
+}
+/**
 * Copies all getter and setter properties from a source object to a target object.
 * Does not copy methods or regular data properties—only accessor properties (get/set).
 * @hidden
@@ -641,13 +655,15 @@ function remove(target, 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.
+Runs the "Init" lifecycle event on a DOM microcomponent instance.
 
 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.
+executes. The {@link DC} constructor calls it once the declared assets are in
+place — synchronously in a bundled build, after the fetch resolves in a
+dev/autoload build — so `oneInit()` always sees the loaded assets. Only `DC`
+instances have an Init lifecycle — the `DC` constructor calls this exclusively,
+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.
 */
@@ -715,16 +731,18 @@ function findMcAncestor(from, key) {
 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:
+to avoid circular references. It starts loading any `static assets` for `MC` and `DC`
+alike (shared per class through `_assetsPromise`), read through the {@link McBase.assets}
+getter. For `DC` subclasses it bootstraps one automatic behaviour:
 
 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.
+The **"Init" lifecycle event** and the DOM attach of auto-attached assets are dispatched
+by the {@link DC} constructor — after the declared assets are in place — so that
+`oneInit()` runs once the instance is fully constructed and its assets are loaded. Plain
+`MC` instances fetch their assets server-side with no DOM attach and no `Init` lifecycle,
+keeping server-side usage lightweight.
 
 ### Plugin extension points
 
@@ -777,20 +795,45 @@ runs once after the constructor.
 var McBase = class {
 	_target;
 	/**
+	* Loaded asset cache, keyed by camelCase descriptor (`'targetHtml'` → `.target.html`).
+	* Inlined by the bundler in a bundled build, filled by `loadAssets()` in dev/autoload.
+	* Read through the {@link McBase.assets} getter.
+	*/
+	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;
+	/**
 	The constructor for the base `McBase` class.
 	
-	Initializes a weak reference to the target and triggers auto-attachment
-	of listeners and initialization lifecycle events.
+	Initializes a weak reference to the target, auto-attaches listeners for `DC`
+	subclasses, and starts loading any `static assets` for `MC` and `DC` alike —
+	a server-side `MC` fetches them with no DOM, a `DC` gets them attached by its
+	own constructor. The load is shared per class through `_assetsPromise`.
 	
 	@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);
-		}
+		const ctor = this.constructor;
+		if (this instanceof DC && this.constructor !== DC) autoAttachListeners(this);
+		const remaining = (ctor.assets ?? []).filter((key) => !ctor._assets[key]);
+		if (remaining.length && !ctor._assetsPromise) ctor._assetsPromise = loadAssets(ctor._originalTag || (this instanceof DC ? this.target.tagName.toLowerCase() : pascalToKebab(ctor.name)), remaining).then((res) => {
+			const loadedAssets = {};
+			remaining.forEach((key, i) => {
+				loadedAssets[key] = res[i];
+			});
+			ctor._assets = Object.assign({}, ctor._assets, loadedAssets);
+			return loadedAssets;
+		});
 	}
 	/**
 	Returns the current target object (DOM node or other data) referenced by this microcomponent.
@@ -808,6 +851,21 @@ var McBase = class {
 	get target() {
 		return this._target.deref();
 	}
+	/**
+	The loaded assets for this component instance.
+	
+	`static assets` are loaded before `oneInit()` fires on a `DC`, so this getter is
+	ready inside the `oneInit()` callback. A server-side `MC` fills it from `loadAssets()`;
+	await `MC._assetsPromise` before reading it. It returns the merged asset record keyed
+	by descriptor: `css` / `targetCss` / `shadowCss` / `shadowHtml` / `targetHtml` arrive
+	as strings, `*Json` entries arrive parsed, and a plain `html` template is returned as a
+	string for `parse()`. An empty object when no assets are declared.
+	
+	@returns A record mapping asset keys to their content.
+	*/
+	get assets() {
+		return this.constructor._assets || {};
+	}
 };
 /**
 @class DC
@@ -865,14 +923,26 @@ and translated into file extensions: `'targetHtml'` → `.target.html`, `'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.
+**Assets are loaded before `oneInit()` fires.** The constructor applies them to the
+target, then dispatches the `Init` lifecycle event — synchronously in a bundled build
+(assets inlined), after the fetch resolves in a dev/autoload build. Inside `oneInit()`
+the loaded assets are read through the {@link DC.assets} getter. Everything ending in
+`Json` arrives parsed; all other files arrive as text.
+
+**Auto-attached assets**: `.css`, `.target.css`, `.shadow.css`, `.target.html` and
+`.shadow.html` are attached automatically by `processAssets()` — CSS is injected into
+the document or shadow scope, HTML is set as `target.innerHTML` / `shadowRoot.innerHTML`,
+and native event handlers in the template (`<button click="this|go">`) are wired.
+
+**Plain `.html` is NOT auto-attached.** It is a template held in {@link DC.assets} for
+components created programmatically with a `data` parameter: in `oneInit()` you compile
+the target markup from template + data with `parse()`.
 
 **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.
+the entries are dropped from `static _assets`. Subsequent instances skip re-processing
+them entirely.
 
 **CSS file roles**:
 
@@ -883,7 +953,9 @@ scope once, like `targetCss`.
 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.
+the bundler, which replaces the `static assets` declaration with `static _assets` (the
+`static assets` line is deleted from the bundled `.js`) and collapses each inlined
+`.[shadow/target].css` / `.html` to a single line, so a bundled build performs no fetches.
 
 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
@@ -895,14 +967,14 @@ The runtime decides whether an asset still needs fetching with `!ctor._assets[ke
 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
+@example static assets read in oneInit
 
 ```ts
 class CartCheckout extends DC {
 static assets = ['targetHtml', 'targetCss', 'configJson'];
 
-oneAssets(ev) {
-const { configJson } = ev.detail.data;
+oneInit() {
+const { configJson } = this.assets;
 console.log(configJson);
 }
 }
@@ -911,6 +983,26 @@ defineCE('cart-checkout', CartCheckout);
 
 `configJson` arrives already parsed into an object.
 
+@example plain .html template compiled with data
+
+```ts
+class UserCard extends DC {
+static assets = ['html', 'targetCss'];
+
+constructor(target: HTMLElement, data: { name: string }) {
+super(target);
+this.data = data;
+}
+
+oneInit() {
+this.target.innerHTML = parse(this.assets.html, this.data);
+}
+}
+defineCE('user-card', UserCard);
+```
+
+`user-card.html` holds the `{name}` template; `parse()` fills it from `data`.
+
 ### `static attributes?: object`
 
 Sets HTML attributes on every instance automatically.
@@ -964,8 +1056,7 @@ internal events that can be caught with handler methods:
 | `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 |
+| `oneInit()` | Constructor finished and declared assets loaded; read them via `this.assets` |
 
 @example Event handlers in action
 
@@ -1080,22 +1171,6 @@ var DC = class DC extends McBase {
 	*/
 	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' }`.
 	*/
@@ -1107,8 +1182,10 @@ var DC = class DC extends McBase {
 	* 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.
+	* 3. Applies any `static attributes` to the target element.
+	* 4. Loads `static assets` (inlined in a bundled build, fetched in dev/autoload),
+	*    applies the auto-attached ones to the target, then fires the `Init` lifecycle
+	*    event — so `oneInit()` runs with the assets loaded and readable via {@link DC.assets}.
 	*
 	* @param target - The host DOM element this component operates on.
 	*/
@@ -1131,43 +1208,24 @@ var DC = class DC extends McBase {
 		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 (Object.keys(ctor._assets).length) {
+			processAssets(this, ctor._assets);
+			for (const onceKey of ["css", "targetCss"]) delete ctor._assets[onceKey];
+			ctor.assets = ctor.assets.filter((key) => key !== "css" && key !== "targetCss");
+		}
+		if (ctor._assetsPromise) ctor._assetsPromise.then((loadedAssets) => {
+			processAssets(this, loadedAssets);
+			for (const onceKey of ["css", "targetCss"]) delete ctor._assets[onceKey];
+			ctor.assets = ctor.assets.filter((key) => key !== "css" && key !== "targetCss");
+			init(this);
+		});
+		else init(this);
 		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
@@ -1524,7 +1582,7 @@ observePlugin(DC);
 class Counter extends DC {
 data = { clicks: 1 };
 
-oneAssets() {
+oneInit() {
 this
 .subscribe('data', (v) => console.log('data →', v))
 .bind('data', this.target);
@@ -1907,7 +1965,7 @@ subsequent calls are no-ops.
 class Counter extends DC {
 data = { clicks: 1 };
 
-oneAssets() {
+oneInit() {
 this
 .subscribe('data', (v) => console.log('data →', v))
 .bind('data', this.target);
@@ -2003,7 +2061,7 @@ formValuePlugin(DC);
 class CheckoutForm extends DC {
 static assets = ['targetHtml'];
 
-oneAssets() {
+oneInit() {
 this
 .formValues(this.target, 'formData')
 .subscribe('formData', (data) => console.log(data))
@@ -2291,7 +2349,7 @@ import { DC, defineCE, formValues } from '@twobirds/microcomponents';
 class MyForm extends DC {
 static assets = ['targetHtml'];
 
-oneAssets() {
+oneInit() {
 formValues(this, 'formData', this.target);
 this.formData.subscribe((data) => console.log('form changed:', data));
 }
@@ -2336,7 +2394,7 @@ formValuePlugin(DC);
 class CheckoutForm extends DC {
 static assets = ['targetHtml'];
 
-oneAssets() {
+oneInit() {
 this
 .formValues(this.target, 'formData')
 .subscribe('formData', (data) => console.log(data))

package/dist/state/index.d.ts

@@ -1,7 +1,10 @@
 /**
 @module State
 */
+/** @group State */
 export { observe, observePlugin, isAlreadyObserved } from './observables.js';
+/** @group State */
 export type { Observable, Callback, Observed, ObservedKey, Unobserved } from './observables.js';
+/** @group State */
 export { formValues, formValuePlugin } from './formValues.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;EAEE;AACF,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChG,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;EAEE;AACF,mBAAmB;AACnB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,mBAAmB;AACnB,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChG,mBAAmB;AACnB,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/state/observables.d.ts

@@ -28,7 +28,7 @@ observePlugin(DC);
 class Counter extends DC {
     data = { clicks: 1 };
 
-    oneAssets() {
+    oneInit() {
         this
         .subscribe('data', (v) => console.log('data →', v))
         .bind('data', this.target);
@@ -220,7 +220,7 @@ subsequent calls are no-ops.
 class Counter extends DC {
     data = { clicks: 1 };
 
-    oneAssets() {
+    oneInit() {
         this
         .subscribe('data', (v) => console.log('data →', v))
         .bind('data', this.target);