@twobirds/microcomponents 0.9.0 → 0.10.1

package/dist/utils/helpers.js

@@ -1,532 +0,0 @@
-/**
-@module Helpers
-
-Small runtime-agnostic utilities shared across the library: environment
-detection, object flattening/comparison, debouncing, accessor copying, and
-kebab-to-PascalCase conversion.
-*/
-import { on, trigger } from './events.js';
-/**
- * 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
- * console.log(isNativeObject({}));
- * console.log(isNativeObject(new Object()));
- * console.log(isNativeObject([]));
- * console.log(isNativeObject(null));
- * ```
- */
-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 } };
- * console.log(JSON.stringify(sortObject(obj)));
- * ```
- */
-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 } };
- * console.log(JSON.stringify(flattenObject(obj)));
- * ```
- */
-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
- * console.log(deepEqual({ a: 1 }, { a: 1 }));
- * console.log(deepEqual({ a: { b: 2 } }, { a: {} }));
- * console.log(deepEqual({ a: NaN }, { a: NaN }));
- * console.log(deepEqual({ a: NaN }, { a: null }));
- * ```
- */
-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' } } };
- * console.log(nameSpace('user.profile.name', data));
- * console.log(nameSpace(['user', 'profile'], data));
- * ```
- */
-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' } };
- * console.log(parse('Hello {user.name}!', data));
- * console.log(parse(['Hi {user.name}', 'Bye {user.name}'], data));
- * ```
- */
-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
- * console.log(kebabToPascal('my-element'));
- * ```
- */
-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();
- * log();
- * ```
- */
-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.
- * @hidden
- * @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>');
- * console.log(elems.map((el) => el.tagName));
- * ```
- */
-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);
-}
-/**
- * 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
- * @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);
- * ```
- */
-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);
-        }
-    }
-}
-/**
- * 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}\``
- */
-const _injectedCSS = new WeakMap();
-export function injectCSS(target, css) {
-    const injected = _injectedCSS.get(target) ?? 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>'
- * });
- * ```
- */
-export 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;
- * });
- * ```
- */
-export function loadAssets(name, assets) {
-    const parseAsset = (asset) => {
-        // Match camelCase variant+ext, e.g. 'shadowCss' → ['shadow','css']
-        const m = asset.match(/^([a-z]+)([A-Z][a-z]*)$/);
-        if (m) {
-            return `./${name.replace(/-/g, '/')}.${m[1]}.${m[2].toLowerCase()}`;
-        }
-        // Plain extension, e.g. 'css' → 'catalog.css'
-        return `./${name.replace(/-/g, '/')}.${asset.toLowerCase()}`;
-    };
-    return Promise.all(assets.map(async (asset) => {
-        const filename = parseAsset(asset);
-        //console.log(filename);
-        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">
- * ```
- */
-export function bindTemplateEvents(rootElement, instance) {
-    // Collect all elements that carry at least one attribute matching a native event name.
-    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();
-            // Check if this attribute name maps to a native event handler property.
-            if (!('on' + lowerName in el))
-                continue;
-            const parts = attr.value.trim().split('|');
-            if (parts.length < 2)
-                continue; // need at least selector and eventname
-            const [selector, event, payload] = parts;
-            // Clean up binding attributes from the DOM.
-            el.removeAttribute(attr.name);
-            // Resolve payload from sibling attribute if present.
-            let payloadData; // intentional
-            if (payload) {
-                try {
-                    payloadData = JSON.parse(payload);
-                }
-                catch {
-                    payloadData = payload;
-                }
-            }
-            // Wire the native event listener.
-            if (selector === 'this' || selector === '') {
-                // Local trigger — fire on the _mc attached to this element.
-                on(el, lowerName, () => instance.trigger(event, payloadData));
-            }
-            else {
-                // Selector-based trigger — query and fire on every match.
-                on(el, lowerName, () => trigger(selector, event, payloadData));
-            }
-        }
-    }
-}

package/dist/utils/index.js

@@ -1,12 +0,0 @@
-/**
-Utils module — events, autoload, and helper utilities.
-
-@module Utilities
-@showGroups
-*/
-/** @group Events */
-export { getMcEventName, trueEventName, off, on, one, trigger, BubbleController, } from './events.js';
-/** @group Autoload */
-export { autoload } from './autoload.js';
-/** @group Helpers */
-export { isBrowser, isNativeObject, sortObject, flattenObject, deepEqual, nameSpace, parse, kebabToPascal, debounce, htmlToElements, copyGettersSetters, injectCSS, processAssets, loadAssets, bindTemplateEvents, } from './helpers.js';

package/dist/utils/resolveComponentPath.js

@@ -1,39 +0,0 @@
-/**
-@module Autoload
-
-Single source of truth for the tag-to-file convention: hyphens become path
-separators, so `my-card` resolves to `./my/card.js`. Imported by the runtime
-autoload loader and by build-time tooling so both agree on the path without
-either duplicating the rule.
-*/
-/**
-The tag-to-path primitive: hyphens become path separators, with no prefix or
-extension. `my-card` → `my/card`. The single source of truth for the
-convention; {@link resolveComponentPath} and build-time tooling both derive
-their paths from it so neither duplicates the rule.
-
-@example Returns `'my/card'` for `my-card`, and `'app/header'` for `app-header`.
-```ts
-tagPath('my-card');
-tagPath('app-header');
-```
-@hidden
-@group Autoload
-*/
-export function tagPath(tag) {
-    return tag.split('-').join('/');
-}
-/**
-Resolves a microcomponent tag name to its autoload module path by prefixing and
-suffixing {@link tagPath}: `my-card` → `./my/card.js`.
-
-@example Returns `'./my/card.js'` for `my-card`, and `'./app/header.js'` for `app-header`.
-```ts
-resolveComponentPath('my-card');
-resolveComponentPath('app-header');
-```
-@group Autoload
-*/
-export function resolveComponentPath(tag) {
-    return './' + tagPath(tag) + '.js';
-}

package/dist/vite/index.d.ts

@@ -1,7 +0,0 @@
-/**
-Vite module — build-time plugins for a bundled Micro Components project.
-
-@module Vite
-*/
-export { loadAssetsPlugin } from './loadAssets.js';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA;;;;EAIE;AAEF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/vite/index.js

@@ -1,6 +0,0 @@
-/**
-Vite module — build-time plugins for a bundled Micro Components project.
-
-@module Vite
-*/
-export { loadAssetsPlugin } from './loadAssets.js';

package/dist/vite/loadAssets.d.ts

@@ -1,36 +0,0 @@
-/**
-Inlines `static assets = [...]` declarations on DC classes for a bundled build: companion
-`.css` / `.html` files are read at build time and embedded as a `static _assets = { ... }`
-property inserted as the first line inside the class body, so `loadAssets()` never fetches
-them at runtime. The original `static assets` line is preserved for debugging purposes.
-
-The plugin ships as its own entry, `@twobirds/microcomponents/vite`, so a project that
-bundles to `public/` imports it without copying the source.
-
-@example
-```ts
-import { loadAssetsPlugin } from '@twobirds/microcomponents/vite';
-
-export default defineConfig({
-    plugins: [loadAssetsPlugin(sourceRoot)],
-});
-```
-
-@module Vite
-*/
-import type { PluginOption } from 'vite';
-/**
- * Vite plugin factory that inlines companion `.css` / `.html` assets into the
- * DC classes declaring them through `static assets = [...]`.
- *
- * @example Register the plugin in a Vite config, pointing at the source root.
- * ```ts
- * import { loadAssetsPlugin } from './vite-plugin-load-assets';
- * export default defineConfig({ plugins: [loadAssetsPlugin(__dirname)] });
- * ```
- *
- * @param rootDir Directory holding the component source files.
- * @returns A Vite plugin option.
- */
-export declare function loadAssetsPlugin(rootDir: string): PluginOption;
-//# sourceMappingURL=loadAssets.d.ts.map

package/dist/vite/loadAssets.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loadAssets.d.ts","sourceRoot":"","sources":["../../src/vite/loadAssets.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;EAmBE;AAIF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAgJzC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAiE9D"}