@twobirds/microcomponents 0.1.21 → 0.2.0

package/dist/utils/helpers.js

@@ -0,0 +1,340 @@
+/**
+@module Helpers
+
+Small runtime-agnostic utilities shared across the library: environment
+detection, object flattening/comparison, debouncing, accessor copying, and
+kebab-to-PascalCase conversion.
+*/
+/**
+ * Determines whether the current runtime environment is a web browser.
+ *
+ * This function works by attempting to access `this` within an anonymous function
+ * and checking if it refers to the global `window` object. It returns `true`
+ * when executed in a browser context, and `false` otherwise (e.g., Node.js).
+ *
+ * Note: While modern environments typically provide more reliable detection mechanisms,
+ * this fallback remains compatible across older runtimes where other detection techniques
+ * may be unreliable.
+ *
+ * @returns `true` if the code is running in a browser environment, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * if (isBrowser()) {
+ *   console.log('Running in a browser');
+ * }
+ * ```
+ */
+export function isBrowser() {
+    return typeof window !== 'undefined' && typeof window.document !== 'undefined';
+}
+/**
+ * Checks if a value is a native JavaScript object (created via {} or new Object()).
+ * @param value - The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ *
+ * @example
+ * ```ts
+ * isNativeObject({});        // true
+ * isNativeObject(new Object()); // true
+ * isNativeObject([]);        // false
+ * isNativeObject(null);      // false
+ * ```
+ */
+export function isNativeObject(value) {
+    return typeof value === 'object' && value !== null && value.constructor === Object;
+}
+/**
+ * Recursively sorts all keys in an object alphabetically, preserving nested structure.
+ * @param source - The object to sort.
+ * @returns A new object with sorted keys at all levels.
+ *
+ * @example
+ * ```ts
+ * const obj = { z: 1, a: { y: 2, b: 3 } };
+ * sortObject(obj); // { a: { b: 3, y: 2 }, z: 1 }
+ * ```
+ */
+export function sortObject(source) {
+    const result = {}, keys = Object.keys(source).sort();
+    // Indexed for: no per-key callback/iterator overhead. ~15x faster than .forEach,
+    // ~10x faster than for-of over the loop body itself (V8, 5M elems), and ~15x faster than .forEach()
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i], value = source[key];
+        if (isNativeObject(value)) {
+            result[key] = sortObject(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Flattens a nested object into a single-level object with dot-separated keys.
+ * Optionally sorts the resulting flat keys alphabetically (default: true).
+ * @param source - The object to flatten.
+ * @param doSort - Whether to sort the resulting keys (default: true).
+ * @returns A flattened object with dot-notation keys.
+ *
+ * @example
+ * ```ts
+ * const obj = { user: { name: 'Alice', age: 30 } };
+ * flattenObject(obj); // { 'user.age': 30, 'user.name': 'Alice' }
+ * ```
+ */
+export function flattenObject(source, doSort = true) {
+    const result = {};
+    const record = source;
+    const names = Object.getOwnPropertyNames(source);
+    // Indexed for: no per-key callback overhead, and no extra copy from spreading
+    // ~10x faster than for-of over the loop body itself (V8, 5M elems), and ~15x faster than .forEach()
+    for (let i = 0; i < names.length; i++) {
+        const propName = names[i], value = record[propName];
+        if (value instanceof Object) {
+            const temp = flattenObject(value, false);
+            for (const j in temp) {
+                result[propName + '.' + j] = temp[j];
+            }
+        }
+        else {
+            result[propName] = value;
+        }
+    }
+    return doSort ? sortObject(result) : result;
+}
+/**
+ * Structural deep-equality using SameValueZero for primitives.
+ *
+ * See {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero}.
+ *
+ * Note: `Map`/`Set` are not structurally compared.
+ *
+ * @param a - The first value to compare.
+ * @param b - The second value to compare.
+ * @returns True if the values are deeply equal, false otherwise.
+ *
+ * @example
+ * ```ts
+ * deepEqual({ a: 1 }, { a: 1 });          // true
+ * deepEqual({ a: { b: 2 } }, { a: {} });  // false
+ * deepEqual({ a: NaN }, { a: NaN });      // true  (SameValueZero)
+ * deepEqual({ a: NaN }, { a: null });     // false
+ * ```
+ */
+export function deepEqual(a, b) {
+    // SameValueZero: identical primitives/refs, plus NaN === NaN.
+    if (a === b || (a !== a && b !== b))
+        return true;
+    /* v8 ignore start */
+    // Beyond SameValueZero, equality needs two non-null objects of the same kind.
+    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null)
+        return false;
+    if (a.constructor !== b.constructor)
+        return false;
+    if (a instanceof Date)
+        return a.getTime() === b.getTime();
+    if (a instanceof RegExp)
+        return a.toString() === b.toString();
+    /* v8 ignore end */
+    if (Array.isArray(a)) {
+        const bArr = b;
+        /* v8 ignore next */
+        if (a.length !== bArr.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqual(a[i], bArr[i]))
+                return false;
+        }
+        return true;
+    }
+    const aObj = a, bObj = b, keys = Object.keys(aObj);
+    if (keys.length !== Object.keys(bObj).length)
+        return false;
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        if (!Object.prototype.hasOwnProperty.call(bObj, key) || !deepEqual(aObj[key], bObj[key]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Retrieves a nested value from an object using a namespace path (dot-separated).
+ * @param ns - The namespace string or array of keys representing the path.
+ * @param obj - The object to traverse.
+ * @returns The value at the specified namespace path, or undefined if not found.
+ *
+ * @example
+ * ```ts
+ * const data = { user: { profile: { name: 'Alice' } } };
+ * nameSpace('user.profile.name', data); // 'Alice'
+ * nameSpace(['user', 'profile'], data);  // { name: 'Alice' }
+ * ```
+ */
+export function nameSpace(ns, obj = {}) {
+    const source = obj;
+    const nsa = typeof ns === 'string' ? ns.split('.') : ns;
+    if (!source || !nsa[0] || !source[nsa[0]]) {
+        return undefined;
+    }
+    if (nsa.length > 1) {
+        const next = source[nsa[0]];
+        if (isNativeObject(next)) {
+            return nameSpace(nsa.slice(1), next);
+        }
+        return undefined;
+    }
+    return source[nsa[0]];
+}
+/**
+ * Parses a template string or object, replacing placeholders in the form of {key.path} with
+ * corresponding values from the provided data object using namespace resolution.
+ * Also recursively processes objects and arrays within the input.
+ * @param template - The string or object to parse (can contain {{placeholder}} expressions).
+ * @param parseThis - The object containing values for placeholder substitution.
+ * @returns The parsed result, with placeholders replaced by actual values.
+ *
+ * @example
+ * ```ts
+ * const data = { user: { name: 'Alice' } };
+ * parse('Hello {user.name}!', data); // 'Hello Alice!'
+ *
+ * parse(['Hi {user.name}', 'Bye {user.name}'], data); // ['Hi Alice', 'Bye Alice']
+ * ```
+ */
+export function parse(template, parseThis, ...rest) {
+    const args = [template, parseThis, ...rest];
+    if (args.length > 2) {
+        while (args.length > 1) {
+            args[0] = parse(args[0], args[1]);
+            args.splice(1, 1);
+        }
+        return args[0];
+    }
+    if (typeof template === 'string') {
+        let result = template;
+        template.match(/\{[^\{\}]*\}/g)?.forEach((pPropname) => {
+            const propname = pPropname.substring(1, pPropname.length - 1), value = nameSpace(propname, parseThis);
+            if (typeof value !== 'undefined') {
+                result = result.replace(pPropname, String(value));
+            }
+        });
+        return result;
+    }
+    else if (isNativeObject(template)) {
+        const record = template;
+        Object.keys(record).forEach((pKey) => {
+            /* v8 ignore next */
+            if (Object.prototype.hasOwnProperty.call(record, pKey)) {
+                record[pKey] = parse(record[pKey], parseThis);
+            }
+        });
+    }
+    return template;
+}
+/**
+ * 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
+ * kebabToPascal('my-element'); // 'MyElement'
+ * ```
+ */
+export function kebabToPascal(str) {
+    return str
+        .split('-') // Split by hyphens
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) // Capitalize each part
+        .join(''); // Join without spaces
+}
+/**
+ * Creates a debounced version of a function that delays execution until after the specified
+ * number of milliseconds have elapsed since the last time this function was invoked.
+ * Useful for rate-limiting expensive operations like event handlers or API calls.
+ * @param func - The function to debounce.
+ * @param milliseconds - The number of milliseconds to delay execution.
+ * @returns A debounced version of the input function.
+ *
+ * @example
+ * ```ts
+ * const log = debounce(() => console.log('called'), 300);
+ * log(); // will only execute once after 300ms of inactivity
+ * ```
+ */
+export function debounce(func, milliseconds) {
+    let timeout;
+    return (...args) => {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            func(...args);
+        }, milliseconds);
+    };
+}
+/**
+ * Parses an HTML string and returns an array of DOM elements.
+ * Handles self-closing tags (XHTML style) by converting them to full closing tags first.
+ * @param html - The HTML string to parse.
+ * @returns An array of HTMLElement objects representing the parsed HTML nodes.
+ *
+ * @example
+ * ```ts
+ * const elems = htmlToElements('<div>Hello</div><span>World</span>');
+ * // [HTMLElement<div>, HTMLElement<span>]
+ * ```
+ */
+export function htmlToElements(html) {
+    const template = document.createElement('template');
+    html = html.replace(/<([A-Za-z0-9\-]*)([^>\/]*)(\/>)/gi, '<$1$2></$1>'); // replace XHTML closing tags by full closing tags
+    template.innerHTML = html;
+    template.content.normalize();
+    return Array.from(template.content.childNodes);
+}
+/**
+ * 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.
+ *
+ * @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');
+ * trueEventName(btn, 'Click');   // 'click'  — native handler exists
+ * trueEventName(btn, 'Update');  // '_mcUpdate' — custom event
+ * ```
+ */
+export function trueEventName(target, eventName) {
+    const lower = eventName.toLowerCase();
+    if ('on' + lower in target)
+        return lower;
+    return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
+}
+/**
+ * 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).
+ * @param source - The source object with getters and/or setters to copy.
+ * @param target - The target object to which the accessors will be copied.
+ *
+ * @example
+ * ```ts
+ * const src = { get name() { return 'Alice'; } };
+ * const tgt = {};
+ * copyGettersSetters(src, tgt);
+ * console.log(tgt.name); // 'Alice'
+ * ```
+ */
+export function copyGettersSetters(source, target) {
+    const descriptors = Object.getOwnPropertyDescriptors(source);
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+        if ('get' in descriptor || 'set' in descriptor) {
+            Object.defineProperty(target, key, descriptor);
+        }
+    }
+}

package/package.json

@@ -1,77 +1,111 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.1.21",
+	"version": "0.2.0",
 	"description": "Micro Components Organization Class",
-	"main": "./dist/microcomponents.ts",
-	"types": "./dist/microcomponents.d.ts",
-	"exports": {
-		".": {
-			"import": "./dist/microcomponents.js"
-		}
-	},
-	"type": "module",
-	"files": [
-		"dist"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"format": "prettier --write \"src/**/*.{ts,js}\"",
-		"lint": "eslint \"src/**/*.ts\" --fix > eslint.log",
-		"typedoc": "typedoc || true",
-		"webpack": "webpack",
-		"clean": "rm -rf build/*; rm -rf dist/*; rm -rf public/*;",
-		"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 ../..",
-		"watch": "inotifywait -m -r -e close_write,create,delete --format '%w%f' src | while read f; do echo \"\nCHANGED: $f\n\"; npm run build > build.log; cat build.log; done"
-	},
-	"author": "Frank Thürigen",
-	"license": "ISC",
-	"devDependencies": {
-		"@typescript-eslint/eslint-plugin": "^8.46.4",
-		"@typescript-eslint/parser": "^8.46.4",
-		"eslint": "^9.39.1",
-		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-prettier": "^5.5.4",
-		"jsmin": "^1.0.1",
-		"prettier": "^3.6.2",
-		"ts-loader": "^9.5.2",
-		"typedoc": "^0.26.11",
-		"typescript": "^5.5.4",
-		"vite": "^7.3.1",
-		"webpack": "^5.97.1",
-		"webpack-cli": "^6.0.1"
-	},
 	"keywords": [
-		"javascript",
-		"library",
-		"native",
+		"API",
 		"DOM manipulation",
-		"lightweight",
-		"standalone",
-		"SPA",
-		"PWA",
-		"ES3",
-		"ES5",
-		"ES6",
-		"ES7",
 		"ES2015",
 		"ES2016",
+		"ES6",
+		"ES7",
+		"PWA",
+		"SPA",
 		"client",
-		"API"
+		"javascript",
+		"library",
+		"lightweight",
+		"native",
+		"standalone"
 	],
-	"repository": {
-		"type": "git",
-		"url": "https://gitlab.com/twoBirds/microcomponents"
-	},
+	"license": "MIT",
+	"author": "Frank Thürigen",
 	"contributors": [
 		{
 			"name": "Frank Thürigen",
 			"email": "fthuerigen@gmail.com"
+		},
+		{
+			"name": "Samuel Braun",
+			"email": "sam@webry.com"
 		}
-	]
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://gitlab.com/twoBirds/microcomponents.git"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/microcomponents.js",
+	"types": "./dist/microcomponents.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/microcomponents.d.ts",
+			"import": "./dist/microcomponents.js"
+		},
+		"./guards": {
+			"types": "./dist/core/mcGuards.d.ts",
+			"import": "./dist/core/mcGuards.js"
+		},
+		"./events": {
+			"types": "./dist/core/events.d.ts",
+			"import": "./dist/core/events.js"
+		},
+		"./elements": {
+			"types": "./dist/core/elements.d.ts",
+			"import": "./dist/core/elements.js"
+		},
+		"./observables": {
+			"types": "./dist/state/observables.d.ts",
+			"import": "./dist/state/observables.js"
+		},
+		"./formValues": {
+			"types": "./dist/state/formValues.d.ts",
+			"import": "./dist/state/formValues.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"format": "oxfmt .",
+		"lint": "oxlint \"src\"",
+		"fix": "oxfmt . && oxlint \"src\" --fix",
+		"check": "tsc --noEmit -p tsconfig.lib.json && tsc -p tsconfig.test.json && tsc -p tsconfig.demo.json && tsc -p tsconfig.node.json",
+		"check:pack": "publint && attw --pack . --profile esm-only",
+		"test": "vitest",
+		"test:run": "vitest run --reporter=verbose",
+		"test:coverage": "vitest run --coverage",
+		"demo:shop": "vite --config demo/shop/vite.config.ts",
+		"demo:shop:bundled": "node vite.shop.bundle.ts",
+		"demo:shop:build": "node vite.shop.ts && pnpm run demo:shop:bundled",
+		"demo:shop:serve": "vite preview --outDir public/shop --port 5174 --host",
+		"typedoc": "typedoc",
+		"bundle": "node vite.build.ts",
+		"clean": "rm -rf dist public",
+		"build": "pnpm run clean && tsc -p tsconfig.lib.json && pnpm run test:coverage && pnpm run bundle && pnpm run check:pack && pnpm run typedoc && pnpm run demo:build && pnpm run demo:shop:build",
+		"demo:build": "node vite.demo.ts",
+		"dev": "vite preview --outDir public/test --port 10000 --host",
+		"doc": "vite preview --outDir public/typedoc --port 11000 --host",
+		"watch": "node watch.ts",
+		"prepublishOnly": "pnpm run build && pnpm run check"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.5",
+		"@types/node": "^22.20.1",
+		"@vitest/coverage-v8": "^4.1.10",
+		"jsdom": "^29.1.1",
+		"oxfmt": "^0.59.0",
+		"oxlint": "^1.74.0",
+		"publint": "^0.3.21",
+		"typedoc": "^0.28.20",
+		"typescript": "^6.0.3",
+		"vite": "^8.1.5",
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=22.18"
+	},
+	"packageManager": "pnpm@11.15.1"
 }

package/dist/MC.d.ts

@@ -1,31 +0,0 @@
-import { LooseObject } from './helpers.js';
-import { BubbleController } from './events.js';
-export interface HTMLMcElement extends HTMLElement {
-    _mc: LooseObject;
-}
-declare class McBase {
-    private _target;
-    constructor(target?: {
-        [key: string]: any;
-    });
-    get target(): any;
-}
-declare class MC extends McBase {
-    constructor(target?: any);
-}
-declare class DC extends McBase {
-    constructor(target: HTMLElement);
-    static add(target: HTMLElement, key: string, element?: any): HTMLMcElement;
-    static remove(target: HTMLElement, key: string): void;
-    off(eventName: string, handler: EventListenerOrEventListenerObject): void;
-    on(eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
-    one(eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
-    trigger(eventName: string, data?: any, bubble?: string, controller?: BubbleController): void;
-    ancestors(): DC[] | null;
-    closest(): DC | null;
-    children(): DC[] | null;
-    descendants(): DC[] | null;
-}
-declare function autoload(enable?: boolean): boolean;
-export { MC, DC, McBase, autoload };
-//# sourceMappingURL=MC.d.ts.map

package/dist/MC.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"MC.d.ts","sourceRoot":"","sources":["../src/MC.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAyB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAsBtE,MAAM,WAAW,aAAc,SAAQ,WAAW;IAajD,GAAG,EAAE,WAAW,CAAC;CACjB;AA+JD,cAAM,MAAM;IACX,OAAO,CAAC,OAAO,CAAe;gBAUlB,MAAM,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE;IAmB3C,IAAI,MAAM,IAAI,GAAG,CAEhB;CACD;AAQD,cAAM,EAAG,SAAQ,MAAM;gBAMV,MAAM,CAAC,EAAE,GAAG;CAGxB;AASD,cAAM,EAAG,SAAQ,MAAM;gBACV,MAAM,EAAE,WAAW;IAgB/B,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,GAAQ,GAAG,aAAa;IAc9E,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM;IAK9C,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kCAAkC;IAalE,EAAE,CACD,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC;IAarC,GAAG,CACF,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC;IAcrC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,GAAQ,EAAE,MAAM,GAAE,MAAY,EAAE,UAAU,CAAC,EAAE,gBAAgB;IAc9F,SAAS,IAAI,EAAE,EAAE,GAAG,IAAI;IAsBxB,OAAO,IAAI,EAAE,GAAG,IAAI;IAcpB,QAAQ,IAAI,EAAE,EAAE,GAAG,IAAI;IAcvB,WAAW,IAAI,EAAE,EAAE,GAAG,IAAI;CAQ1B;AAwKD,iBAAS,QAAQ,CAAC,MAAM,GAAE,OAAc,GAAG,OAAO,CAuBjD;AAUD,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC"}