@twobirds/microcomponents 0.1.21 → 0.2.0

package/dist/types/mcTypes.d.ts

@@ -0,0 +1,201 @@
+/**
+@module Type layer
+
+Pure type layer of the microcomponent system.
+
+RULE: types only — no runtime exports, no imports. It sits at the bottom of the
+dependency graph so every other module can import from it without cycles.
+*/
+/** The bubble control handle passed to event handlers; `BubbleController` in events.ts implements it. */
+export interface McBubbleController {
+    stopped: boolean;
+    stop(): void;
+}
+/** One bubbling direction: `l` local dispatch, `u` up to ancestors, `d` down to descendants. */
+export type BubbleDirection = 'l' | 'u' | 'd';
+/**
+The `bubble` argument of `trigger()`: one to three {@link BubbleDirection} letters
+combined — e.g. `'l'`, `'lu'`, `'lud'` — to dispatch locally and/or propagate up
+and down in one call.
+*/
+export type BubbleDirections = BubbleDirection | `${BubbleDirection}${BubbleDirection}` | `${BubbleDirection}${BubbleDirection}${BubbleDirection}`;
+/**
+The `detail` of a microcomponent event: the payload under `data`, the bubble
+control handle under `control`.
+
+@template D - The payload type under `data`.
+*/
+export interface McDetail<D = unknown> {
+    data: D;
+    control: McBubbleController;
+}
+/**
+The function `on()` / `one()` accept as an event handler: it receives an
+{@link McEvent} carrying payload `D`.
+
+@template D - The payload type under `ev.detail.data`.
+*/
+export type McEventHandler<D = unknown> = (ev: McEvent<D>) => void;
+/**
+The event object passed to `on()` / `one()` handlers — a `CustomEvent` carrying
+payload `D`. Short for `CustomEvent<McDetail<D>>`.
+
+Annotate a handler with `McEvent<D>`, or skip the annotation when the event name
+is in the component's event map (`EM` on `DC`) and let it be inferred.
+
+@example
+```ts
+cart.on('CartUpdate', (ev: McEvent<{ count: number }>) => {
+    ev.detail.data.count; // number
+    ev.detail.control.stop(); // stop bubbling
+});
+```
+
+@template D - The payload type under `ev.detail.data`.
+*/
+export type McEvent<D = unknown> = CustomEvent<McDetail<D>>;
+/**
+The payload type of event `K`: its entry in the event map `EM`, or the fallback
+`D` when `K` is not in the map.
+
+@template EM - Event map: `event name → payload type`.
+@template K - The event name.
+@template D - Fallback payload for unmapped names.
+*/
+export type McPayloadOf<EM, K extends string, D = unknown> = K extends keyof EM ? EM[K] : D;
+declare global {
+    /**
+    App-wide map of registry key names to component types. Augment it next to a
+    component definition and keyed lookups (`isMcDOM(el, 'cart')`, `closest('cart')`,
+    `ancestors` / `children` / `descendants`) type themselves from it.
+
+    Presence is checked at runtime; the key → type mapping is a convention. Where
+    you need it proven, use `DC.get(el, 'cart', Cart)` instead.
+
+    @example
+    ```ts
+    declare global {
+        interface McRegistry {
+            cart: Cart;
+        }
+    }
+
+    const el = document.querySelector('form');
+    if (el && isMcDOM(el, 'cart')) {
+        el._mc.cart.addItem(item); // Cart
+    }
+    ```
+    */
+    interface McRegistry {
+    }
+}
+/**
+The public surface of a DOM microcomponent controller — what `DC` exposes per
+instance. The registry types reference this instead of the `DC` class so the
+file stays import-free (`DC implements McController`).
+
+`trigger`'s `bubble` is `string` here, not `BubbleDirections`, because this file
+cannot import from events.ts; `DC` narrows it.
+
+@template T - The host element type.
+*/
+export interface McController<T extends HTMLElement = HTMLElement> {
+    /** The host DOM element this controller is attached to. */
+    readonly target: T;
+    off<D = unknown>(eventName: string, handler: McEventHandler<D>): void;
+    off(eventName: string, handler: EventListenerOrEventListenerObject): void;
+    on<D = unknown>(eventName: string, handler: McEventHandler<D>): McEventHandler<D>;
+    on(eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
+    one<D = unknown>(eventName: string, handler: McEventHandler<D>): McEventHandler<D>;
+    one(eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
+    trigger(eventName: string, data?: unknown, bubble?: string, controller?: McBubbleController): void;
+    ancestors<R extends Record<string, unknown> = Record<never, never>>(): (McController & R)[];
+    ancestors<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>)[];
+    closest<R extends Record<string, unknown> = Record<never, never>>(): (McController & R) | null;
+    closest<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>) | null;
+    children<R extends Record<string, unknown> = Record<never, never>>(): (McController & R)[];
+    children<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>)[];
+    descendants<R extends Record<string, unknown> = Record<never, never>>(): (McController & R)[];
+    descendants<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>)[];
+}
+/**
+Opt-in type check for native-event handler methods (`onClick`, `onePointerdown`,
+…). Add it with `implements` and each `on<Event>` / `one<Event>` method is
+checked against the correct DOM event type; other methods are left alone.
+Type-only — nothing exists at runtime.
+
+@example
+```ts
+class Panel extends DC implements McNativeEventHandlers {
+    onClick(ev: MouseEvent) {}       // ✓ checked against 'click'
+    // onClick(ev: KeyboardEvent) {} // ✗ wrong event type
+}
+```
+*/
+export type McNativeEventHandlers = {
+    [K in keyof GlobalEventHandlersEventMap as `on${Capitalize<K>}` | `one${Capitalize<K>}`]?: (ev: GlobalEventHandlersEventMap[K]) => void;
+};
+/**
+A DOM element that hosts microcomponents: the element type `T` plus an `_mc`
+registry. `R` holds the known entries (`key → element type`); there is no string
+index, so an unregistered key is a compile error. Chained `add()` calls merge
+their entries into `R`.
+
+@template T - The host element type (defaults to `HTMLElement`).
+@template R - Known `_mc` entries (defaults to none).
+@example
+```ts
+const withA = DC.add(form, 'a', { a: 0 });
+withA._mc.a.a; // number
+withA._mc.b;   // ✗ never registered
+```
+*/
+export type McHost<T extends HTMLElement = HTMLElement, R extends Record<string, unknown> = Record<never, never>> = T & {
+    /** The hosted microcomponents: the controller API plus one entry per `add()` key. */
+    _mc: McController<T> & R;
+};
+/**
+The element type behind a target: unwraps `McHost<U, R>` back to `U`, identity
+for a plain element. Keeps chained `add()` calls from nesting.
+
+@template T - A plain or enhanced element type.
+*/
+export type McHostOf<T extends HTMLElement> = T extends {
+    _mc: McController<infer U>;
+} ? U : T;
+/**
+The known `_mc` entries of a target as a flat `key → element type` record: the
+`add()` entries with the controller members stripped out, empty for a plain
+element. This is what lets chained `add()` calls stay flat instead of nesting.
+
+@template T - A plain or enhanced element type.
+*/
+export type McEntriesOf<T> = T extends {
+    _mc: infer M;
+} ? {
+    [P in keyof M as P extends string ? string extends P ? never : P extends keyof McController ? never : [M[P]] extends [never] ? never : P : never]: M[P];
+} : Record<never, never>;
+/** Merges two records into one flat record, so registry entries show as a single object. */
+export type McMerged<A, B> = A & B extends infer U ? {
+    [K in keyof U]: U[K];
+} : never;
+/**
+The type `remove()` asserts onto the caller's reference: on an enhanced target the
+removed key is poisoned to `never` (member access becomes a compile error); a
+plain target is left untouched. A later `add()` re-registers the key cleanly.
+
+@template T - A plain or enhanced element type.
+@template K - The key being removed.
+*/
+export type McRemoved<T extends HTMLElement, K extends string> = T extends {
+    _mc: McController;
+} ? {
+    _mc: Record<K, never>;
+} : unknown;
+declare global {
+    interface CustomElementConstructor {
+        /** Builds the element for a host node when `new DefinitionClass(node)` throws. */
+        create?(node: HTMLElement): unknown;
+    }
+}
+//# sourceMappingURL=mcTypes.d.ts.map

package/dist/types/mcTypes.d.ts.map

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

package/dist/types/mcTypes.js

@@ -0,0 +1,9 @@
+/**
+@module Type layer
+
+Pure type layer of the microcomponent system.
+
+RULE: types only — no runtime exports, no imports. It sits at the bottom of the
+dependency graph so every other module can import from it without cycles.
+*/
+export {};

package/dist/utils/helpers.d.ts

@@ -0,0 +1,195 @@
+/**
+@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 declare function isBrowser(): boolean;
+/**
+ * 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 declare function isNativeObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 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 declare function sortObject<T extends Record<string, unknown>>(source: T): T;
+/**
+ * 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 declare function flattenObject(source: object, doSort?: boolean): Record<string, unknown>;
+/**
+ * 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 declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * 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 declare function nameSpace(ns: string | string[], obj?: object): unknown;
+/**
+ * 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 declare function parse<T = string | object | unknown[]>(template: T, parseThis: object, ...rest: unknown[]): T;
+/**
+ * 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 declare function kebabToPascal(str: string): string;
+/**
+ * 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 declare function debounce<A extends unknown[]>(func: (...args: A) => unknown, milliseconds: number): (...args: A) => void;
+/**
+ * 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 declare function htmlToElements(html: string): HTMLElement[];
+/**
+ * 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 declare function trueEventName(target: HTMLElement, eventName: string): string;
+/**
+ * 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 declare function copyGettersSetters(source: object, target: object): void;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/utils/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAiB1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqB7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAiCzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,GAAE,MAAW,GAAG,OAAO,CAe1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,EACpD,QAAQ,EAAE,CAAC,EACX,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,OAAO,EAAE,GAChB,CAAC,CAgCH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,UAKxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAC3C,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,EAC7B,YAAY,EAAE,MAAM,GAClB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAStB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAU1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOvE"}