@twobirds/microcomponents 0.1.20 → 0.1.21

package/dist/observables.ts

@@ -1,15 +1,29 @@
-'use strict';
+import { LooseObject, flattenObject, debounce, deepEqual, copyGettersSetters } from './helpers.js';
+import { HTMLMcElement, DC } from './MC.js';
+import { trigger } from './events.js';
 
-import { LooseObject, debounce, deepEqual, flattenObject, copyGettersSetters } from './helpers.js';
-
-import { DC, HTMLMcElement, trigger } from './MC.js';
+/**
+Determines if a value is an observable object.
 
+@param value - The value to check.
+@returns `true` if the value is a non-null object, otherwise `false`.
+*/
 function isObservableObject(value: any): boolean {
 	return value != null && typeof value === 'object';
 }
 
 type Callback = (value: any) => void;
 
+/**
+Extracts placeholder names from an HTML element's attributes and text content.
+
+Placeholders are strings enclosed in curly braces `{}`. This function scans
+all attributes and direct child text nodes of the target element for placeholders
+and returns them as an array of unique names (without braces).
+
+@param target - The HTMLElement to scan for placeholders.
+@returns An array of placeholder names found within the element's attributes and text content.
+*/
 function getPlaceholders(target: HTMLElement): string[] {
 	let placeholders: Set<string> = new Set(),
 		regEx = /\{[^\{\}]*\}/g;
@@ -18,8 +32,10 @@ function getPlaceholders(target: HTMLElement): string[] {
 	(target.getAttributeNames ? target.getAttributeNames() : [])
 		.filter((attr) => target.getAttribute(attr)?.match(regEx)) // extract placeholder(s)
 		.forEach((attr) => {
-			let placeholders: Set<string> = new Set(target.getAttribute(attr)?.match(regEx));
-			placeholders.forEach((placeholder) => placeholders.add(placeholder.replace(/[\{\}]/g, '')));
+			let attrPlaceholders: Set<string> = new Set(target.getAttribute(attr)?.match(regEx));
+			attrPlaceholders.forEach((attrPlaceholder: string) =>
+				placeholders.add(attrPlaceholder.replace(/[\{\}]/g, ''))
+			);
 		});
 
 	// scan children text nodes
@@ -31,21 +47,38 @@ function getPlaceholders(target: HTMLElement): string[] {
 			);
 		})
 		.forEach((childNode) => {
-			((childNode as any).nodeValue || '').match(regEx).forEach((placeholder: string) => {
-				placeholders.add(placeholder.replace(/[\{\}]/g, ''));
-			});
+			let textContent: string = childNode?.nodeValue || '';
+			let contentPlaceholders = textContent.match(regEx) as string[];
+			contentPlaceholders.forEach((textNodePlaceholder) =>
+				placeholders.add(textNodePlaceholder.replace(/[\{\}]/g, ''))
+			);
 		});
 
-	// extract {} and return result
-	return [...placeholders].map((placeholder) => placeholder.replace(/[\{\}]/g, ''));
+	return [...placeholders];
 }
 
 const inputs = [HTMLInputElement, HTMLSelectElement, HTMLTextAreaElement];
 
+/**
+A class that manages placeholders within an HTML element and updates them dynamically.
+
+This class extends `DC` (Data Controller) and processes the target element to identify
+placeholder patterns in attributes and text nodes. It then observes changes on its internal
+data object and updates the corresponding DOM locations when notified of changes.
+*/
 class Placeholders extends DC {
 	data: LooseObject = {};
 	oldDisplay?: string = '';
 
+	/**
+	Creates a new `Placeholders` instance for the given HTML element.
+	
+	Initializes the internal data with empty strings for each placeholder
+	found in the target and starts observing the data object. Attaches
+	callbacks to update placeholders as needed.
+	
+	@param target - The HTMLElement to process for placeholders.
+	*/
 	constructor(target: HTMLElement) {
 		super(target);
 		getPlaceholders(target).forEach((property) => (this.data[property] = ''));
@@ -63,7 +96,7 @@ class Placeholders extends DC {
 			.forEach((attr: string) => {
 				let placeholders: Set<string> = new Set(target.getAttribute(attr)?.match(/\{[^\{\}]*\}/g));
 				// attach callback
-				this.data.observe(
+				this.data.subscribe(
 					((template: string) => (data: LooseObject) => {
 						let result: string = template;
 						placeholders.forEach((placeholder) => {
@@ -91,7 +124,7 @@ class Placeholders extends DC {
 				let placeholders: Set<string> = new Set(childNode.nodeValue.match(/\{[^\{\}]*\}/g));
 
 				// attach callback
-				this.data.observe(
+				this.data.subscribe(
 					((template: string) => (data: LooseObject) => {
 						let result: string = template;
 						placeholders.forEach((placeholder) => {
@@ -126,6 +159,14 @@ class Placeholders extends DC {
 			});
 	}
 
+	/**
+	Handles a `data` custom event to update the internal placeholder data.
+	
+	Extracts matching keys from the event's detail data and updates only those
+	properties in the internal `data` object that were previously defined as placeholders.
+	
+	@param ev - The CustomEvent containing new data to merge into the placeholders.
+	*/
 	onData(ev: CustomEvent) {
 		let data: LooseObject = {};
 		Object.keys(ev.detail.data).forEach((key) => {
@@ -135,6 +176,12 @@ class Placeholders extends DC {
 	}
 }
 
+/**
+Finds all elements within a given scope that contain placeholders.
+
+@param target - The HTMLElement, DocumentFragment, or ShadowRoot to search.
+@returns An array of HTMLElements containing placeholder patterns.
+*/
 function getPlaceholderElements(
 	target: HTMLElement | DocumentFragment | ShadowRoot
 ): HTMLElement[] {
@@ -146,6 +193,14 @@ function getPlaceholderElements(
 	return elements as HTMLElement[];
 }
 
+/**
+Applies placeholder support to an element and its descendants.
+
+This function scans the provided target for elements containing placeholders
+and attaches a `Placeholders` controller instance to each one if not already present.
+
+@param element - The HTMLElement, DocumentFragment, or ShadowRoot to process.
+*/
 function makePlaceholders(element: HTMLElement | DocumentFragment | ShadowRoot): void {
 	getPlaceholderElements(element).forEach((e: HTMLElement) => {
 		if ((e as HTMLMcElement)?._mc?._placeholders) return;
@@ -153,11 +208,17 @@ function makePlaceholders(element: HTMLElement | DocumentFragment | ShadowRoot):
 	});
 }
 
+/**
+Interface representing an observable object that supports subscription, notification, and DOM binding.
+
+Observable objects track registered callbacks and invoke them when their internal state changes.
+They can also be bound to a DOM target to automatically update placeholder values in the view layer.
+*/
 export type Observable = {
-	observe: (cb: Callback) => void;
-	notify: () => void;
-	bind: (target: HTMLElement | DocumentFragment | ShadowRoot) => void;
-	callbacks: Array<Function>;
+	subscribe: (cb: Callback) => void; // Registers a callback function to be invoked when the observable is notified.
+	notify: () => void; // Notifies all registered callbacks with the current observable data.
+	bind: (target: HTMLElement | DocumentFragment | ShadowRoot) => void; // Binds the observable to a DOM target, setting up placeholder updates.
+	callbacks: Array<Function>; // Array of registered callback functions.
 };
 
 type Class<T> = new (...args: any[]) => T;
@@ -165,7 +226,15 @@ type Class<T> = new (...args: any[]) => T;
 // repository for observable class wrappers
 const classRepo: LooseObject = {};
 
-// creates a new observable class wrapper
+/**
+Creates a new observable wrapper class for the given value's constructor.
+
+Returns a subclass of the original constructor that implements the Observable interface,
+allowing observation and notification of changes. The new class is cached in `classRepo`.
+
+@param val - The value whose constructor should be wrapped with observable behavior.
+@returns A new Observable class that wraps the original constructor.
+*/
 function makeObservable(val: any): Class<typeof val> {
 	const Constructor = val.constructor,
 		ConstructorName: string = Constructor.name;
@@ -193,11 +262,27 @@ function makeObservable(val: any): Class<typeof val> {
 			this.#callbacks = callbacks;
 		}
 
-		observe(callback: Function) {
+		/**
+		Registers a callback function to be invoked when the observable object is notified.
+		
+		@param callback - The function to invoke on notification.
+		@returns This instance for chaining.
+		*/
+		subscribe(callback: Function) {
 			this.#callbacks.push(callback);
 			return this;
 		}
 
+		/**
+		Binds the observable to a DOM target, setting up placeholder updates and
+		triggering initial callbacks.
+		
+		Scans the target and its descendants for placeholders and registers handlers
+		to update them with flattened data on notification.
+		
+		@param target - The HTMLElement, DocumentFragment, or ShadowRoot to bind.
+		@returns This instance for chaining.
+		*/
 		bind(target: HTMLElement | DocumentFragment | ShadowRoot) {
 			const iso = isObservableObject(this.valueOf());
 
@@ -229,6 +314,15 @@ function makeObservable(val: any): Class<typeof val> {
 			return this;
 		}
 
+		/**
+		Notifies registered callbacks with the current observable data.
+		
+		Clones the internal value (if it's an object and not an array) before passing
+		to callbacks. Respects the internal `#notify` flag that can suppress notifications.
+		
+		@param notify - Optional boolean override for the notification state.
+		@returns This instance for chaining.
+		*/
 		notify(notify?: boolean) {
 			let data =
 				isObservableObject(this.valueOf()) && this.valueOf() instanceof Array === false
@@ -255,11 +349,28 @@ function makeObservable(val: any): Class<typeof val> {
 	return ObservableClass;
 }
 
+/**
+Retrieves or creates an observable wrapper class for the given value.
+
+@param val - The value whose constructor should be wrapped with observable behavior.
+@returns A class that wraps the original constructor and implements observable functionality.
+*/
 function getConstructor(val: any): Class<typeof val> {
 	let key: string = val.constructor.name;
 	return classRepo[key] || makeObservable(val);
 }
 
+/**
+Makes a target object's properties observable by replacing them with wrapped values.
+
+Wraps each property of `target` that is not already observable (and meets criteria)
+in an observable wrapper. Also sets up deep change detection for objects and
+debounced notifications when the data changes.
+
+@param target - The LooseObject whose properties should be made observable.
+@param propertyName - Optional specific property name to make one property observable instead of all properties.
+@returns The original target object, now with observable properties.
+*/
 export const observe = (target: LooseObject, propertyName?: string): LooseObject => {
 	let keys = !propertyName ? [...Object.getOwnPropertyNames(target)] : [propertyName];
 
@@ -267,7 +378,7 @@ export const observe = (target: LooseObject, propertyName?: string): LooseObject
 		if (
 			target.hasOwnProperty(key) &&
 			typeof target[key] !== 'function' &&
-			!target?.[key]?.constructor?.prototype?.observe
+			!target?.[key]?.constructor?.prototype?.subscribe
 		) {
 			if (key[0] === '_' || target?.[key] === undefined) return target;
 			let val: any = target[key];
@@ -297,7 +408,7 @@ export const observe = (target: LooseObject, propertyName?: string): LooseObject
 						let iso = isObservableObject(o.valueOf()) && o.valueOf() instanceof Array === false;
 						if (iso) {
 							// is observable object
-							if (o?.constructor?.prototype?.observe === undefined) {
+							if (o?.constructor?.prototype?.subscribe === undefined) {
 								// not observed yet
 								o = new (getConstructor(val) as Class<typeof val>)(
 									structuredClone(Object.assign({}, val))

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.1.20",
+	"version": "0.1.21",
 	"description": "Micro Components Organization Class",
 	"main": "./dist/microcomponents.ts",
 	"types": "./dist/microcomponents.d.ts",
@@ -16,14 +16,14 @@
 	"sideEffects": false,
 	"scripts": {
 		"format": "prettier --write \"src/**/*.{ts,js}\"",
-		"lint": "eslint \"src/**/*.{ts}\" --fix > eslint.log",
-		"typedoc": "typedoc",
+		"lint": "eslint \"src/**/*.ts\" --fix > eslint.log",
+		"typedoc": "typedoc || true",
 		"webpack": "webpack",
 		"clean": "rm -rf build/*; rm -rf dist/*; rm -rf public/*;",
-		"prep": "cp -R src/* build/ || true; mkdir public || true; npm run typedoc; npm run format; npm run lint;",
-		"copyToDist": "cp build/*.js dist; cp public/microcomponents.min.js public/test; cp -R build/*.ts* dist; cp *.svg dist;",
-		"copyToPublic1": "cp dist/*.* public; cp dist/*.* public/test;",
-		"copyToPublic2": "cp -R assets/* public || true; cp -R build/* public/; cp dist/MicroComponents.svg public; cp public/MicroComponents.svg public/test;",
+		"prep": " mkdir build || true; cp -r src/* build/ || true; mkdir public || true; npm run format; npm run lint;",
+		"copyToDist": "cp build/*.js dist; cp -r build/*.ts* dist; cp *.svg dist;",
+		"copyToPublic1": "cp -r build/test public; cp build/* public/test/; cp build/* public; cp -r assets/* public || true; cp -r build/src/test/* public/test || true;",
+		"copyToPublic2": "cp dist/MicroComponents.svg public; cp public/MicroComponents.svg public/test;",
 		"build": "npm run clean; npm run prep; tsc; npm run webpack; npm run copyToDist; npm run copyToPublic1; npm run copyToPublic2;",
 		"dev": "cd public; php -S 0.0.0.0:10000; cd ..",
 		"doc": "cd public/typedoc; php -S 0.0.0.0:11000; cd ../..",