smart-lifecycle 0.1.1

package/dist/rendering/templates/template-provider.factory.js

@@ -0,0 +1,42 @@
+import { TemplateProvider } from "./template-provider.js";
+import { StaticBindingResolver } from "../bindings/static-binding-resolver.js";
+import { RulesResolver } from "../bindings/rules-resolver.js";
+/**
+ * Factory for creating TemplateProvider instances.
+ * Implements the Factory Pattern for centralized object creation.
+ *
+ * @description
+ * Provides a centralized way to create TemplateProvider instances with their dependencies.
+ * Ensures consistent dependency injection and allows for easy testing and mocking.
+ *
+ * @example
+ * ```typescript
+ * const provider = TemplateProviderFactory.createDefault(metadataSource);
+ * const template = await provider.getSource(component, options);
+ * ```
+ */
+export class TemplateProviderFactory {
+    /**
+     * Creates a TemplateProvider with default dependencies.
+     *
+     * @param metadataSource - Optional metadata source for component metadata lookup
+     * @returns A fully configured TemplateProvider instance
+     */
+    static createDefault(metadataSource) {
+        const staticBindingResolver = new StaticBindingResolver();
+        const rulesResolver = new RulesResolver();
+        return new TemplateProvider(staticBindingResolver, rulesResolver, metadataSource);
+    }
+    /**
+     * Creates a TemplateProvider with custom dependencies.
+     *
+     * @param staticBindingResolver - Custom static binding resolver implementation
+     * @param rulesResolver - Custom rules resolver implementation
+     * @param metadataSource - Optional metadata source for component metadata lookup
+     * @returns A TemplateProvider instance with custom dependencies
+     */
+    static createWithDependencies(staticBindingResolver, rulesResolver, metadataSource) {
+        return new TemplateProvider(staticBindingResolver, rulesResolver, metadataSource);
+    }
+}
+//# sourceMappingURL=template-provider.factory.js.map

package/dist/rendering/templates/template-provider.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.factory.js","sourceRoot":"","sources":["../../../src/rendering/templates/template-provider.factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAI9D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,uBAAuB;IAClC;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAClB,cAA2C;QAE3C,MAAM,qBAAqB,GAAG,IAAI,qBAAqB,EAAE,CAAC;QAC1D,MAAM,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC;QAE1C,OAAO,IAAI,gBAAgB,CACzB,qBAAqB,EACrB,aAAa,EACb,cAAc,CACf,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAC3B,qBAAwG,EACxG,aAA+E,EAC/E,cAA2C;QAE3C,OAAO,IAAI,gBAAgB,CACzB,qBAAqB,EACrB,aAAa,EACb,cAAc,CACf,CAAC;IACJ,CAAC;CACF"}

package/dist/rendering/templates/template-provider.interface.d.ts

@@ -0,0 +1,32 @@
+import { SmartComponent } from '../../core/smart-component.js';
+import { RenderOptions } from '../render-engine.js';
+/**
+ * Defines the responsibility of retrieving component templates from metadata and preprocessing.
+ *
+ * @description
+ * Defines the contract for retrieving component templates from metadata and preprocessing
+ * static bindings like [[CONSTANT]] before reactive compilation.
+ */
+export interface ITemplateProvider {
+    /**
+     * Retrieves and preprocesses the template source for a component.
+     *
+     * @param component - The component instance
+     * @param options - Render options containing host element for host projection content capture
+     * @returns Promise resolving to preprocessed template HTML string
+     * @throws Error if no template found in component metadata
+     *
+     * @example
+     * ```typescript
+     * import { TemplateProviderFactory } from './template-provider.factory.js';
+     *
+     * const provider = TemplateProviderFactory.createDefault();
+     * const template = await provider.getSource(
+     *   myComponent,
+     *   renderOptions
+     * );
+     * ```
+     */
+    getSource(component: SmartComponent, options: RenderOptions<SmartComponent>): Promise<string>;
+}
+//# sourceMappingURL=template-provider.interface.d.ts.map

package/dist/rendering/templates/template-provider.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.interface.d.ts","sourceRoot":"","sources":["../../../src/rendering/templates/template-provider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CACP,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB"}

package/dist/rendering/templates/template-provider.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=template-provider.interface.js.map

package/dist/rendering/templates/template-provider.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.interface.js","sourceRoot":"","sources":["../../../src/rendering/templates/template-provider.interface.ts"],"names":[],"mappings":""}

package/dist/rendering/templates/template-provider.js

@@ -0,0 +1,104 @@
+export class TemplateProvider {
+    /**
+     * Static binding resolver for [[CONSTANT]] preprocessing
+     */
+    staticBindingResolver;
+    /**
+     * Rules resolver for [[RULES.field]] preprocessing
+     */
+    rulesResolver;
+    /**
+     * Read-only metadata source for component metadata lookup
+     */
+    metadataSource;
+    /**
+     * Initializes a new instance of TemplateProvider.
+     *
+     * @param staticBindingResolver - Resolver for static constant bindings
+     * @param rulesResolver - Resolver for validation rules bindings
+     * @param metadataSource - Read-only source for component metadata lookup
+     * @throws Error if any dependency is null or undefined
+     */
+    constructor(staticBindingResolver, rulesResolver, metadataSource) {
+        if (!staticBindingResolver)
+            throw new Error("StaticBindingResolver is required");
+        if (!rulesResolver)
+            throw new Error("RulesResolver is required");
+        this.staticBindingResolver = staticBindingResolver;
+        this.rulesResolver = rulesResolver;
+        this.metadataSource = metadataSource;
+    }
+    /**
+     * Retrieves and preprocesses the template source for a component
+     *
+     * @description
+     * Gets template HTML from component metadata and resolves static constants and rules.
+     *
+     * @param component - Component instance
+     * @param options - Render options with hostElement
+     * @returns Promise<string> - Template HTML with [[CONSTANT]] and [[RULES.field]] bindings resolved
+     * @throws Error if no template found in metadata
+     *
+     * @example
+     * ```typescript
+     * // Component with constants and rules
+     * @SmartRender({
+     *   selector: 'login-form',
+     *   constants: {
+     *     Styles: { INPUT: 'form-control' },
+     *     Events: { SUBMIT: 'login-submit' }
+     *   },
+     *   template: `
+     *     <form>
+     *       <input [[RULES.username]] class="[[Styles.INPUT]]" placeholder="Username" />
+     *       <input [[RULES.password]] class="[[Styles.INPUT]]" type="password" placeholder="Password" />
+     *       <button event="[[Events.SUBMIT]]">Login</button>
+     *     </form>
+     *   `
+     * })
+     * class LoginForm extends SmartComponent {
+     *   rules = {
+     *     username: { required: true, minlength: 3 },
+     *     password: { required: true, minlength: 8 }
+     *   };
+     * }
+     *
+     * // After getSource():
+     * // `<form>
+     * //    <input required minlength="3" class="form-control" placeholder="Username" />
+     * //    <input required minlength="8" class="form-control" type="password" placeholder="Password" />
+     * //    <button event="login-submit">Login</button>
+     * //  </form>`
+     * ```
+     */
+    async getSource(component, options) {
+        if (!component)
+            throw new Error("Component is required");
+        if (!options)
+            throw new Error("Options are required");
+        const metadata = this.metadataSource?.get(options.componentId);
+        let template = metadata?.template || "<slot></slot>";
+        if (metadata?.constants) {
+            const hostElement = options.hostElement ?? component;
+            const resolvedConstants = typeof metadata.constants === "function"
+                ? metadata.constants(hostElement)
+                : metadata.constants;
+            template = this.staticBindingResolver.resolve(template, resolvedConstants, component.constructor.name);
+        }
+        // Resolve [[RULES.field]] bindings using component.rules (duck-typed: only present on form components)
+        if (this.hasRules(component) && Object.keys(component.rules).length > 0) {
+            template = this.rulesResolver.resolve(template, component.rules, component.constructor.name);
+        }
+        return template;
+    }
+    /**
+     * Type guard — returns true when a component has validation rules (duck-typing).
+     * Not all components are forms; rules are only present when injected via ctx.rules()
+     * or assigned explicitly. Avoids polluting the SmartComponent base class.
+     */
+    hasRules(component) {
+        const candidate = component["rules"];
+        return typeof candidate === "object" && candidate !== null;
+    }
+}
+//# sourceMappingURL=template-provider.js.map

package/dist/rendering/templates/template-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.js","sourceRoot":"","sources":["../../../src/rendering/templates/template-provider.ts"],"names":[],"mappings":"AA6CA,MAAM,OAAO,gBAAgB;IAC3B;;OAEG;IACc,qBAAqB,CAAyB;IAE/D;;OAEG;IACc,aAAa,CAAiB;IAE/C;;OAEG;IACc,cAAc,CAAyC;IAExE;;;;;;;OAOG;IACH,YACE,qBAA6C,EAC7C,aAA6B,EAC7B,cAA2C;QAE3C,IAAI,CAAC,qBAAqB;YACxB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,IAAI,CAAC,aAAa;YAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAEjE,IAAI,CAAC,qBAAqB,GAAG,qBAAqB,CAAC;QACnD,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,KAAK,CAAC,SAAS,CACb,SAAyB,EACzB,OAAsC;QAEtC,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAEtD,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC/D,IAAI,QAAQ,GAAG,QAAQ,EAAE,QAAQ,IAAI,eAAe,CAAC;QAErD,IAAI,QAAQ,EAAE,SAAS,EAAE,CAAC;YACxB,MAAM,WAAW,GACf,OAAO,CAAC,WAAW,IAAK,SAAoC,CAAC;YAC/D,MAAM,iBAAiB,GACrB,OAAO,QAAQ,CAAC,SAAS,KAAK,UAAU;gBACtC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAC;gBACjC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;YAEzB,QAAQ,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAC3C,QAAQ,EACR,iBAAiB,EACjB,SAAS,CAAC,WAAW,CAAC,IAAI,CAC3B,CAAC;QACJ,CAAC;QAED,uGAAuG;QACvG,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxE,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CACnC,QAAQ,EACR,SAAS,CAAC,KAAK,EACf,SAAS,CAAC,WAAW,CAAC,IAAI,CAC3B,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACK,QAAQ,CACd,SAAkB;QAElB,MAAM,SAAS,GAAI,SAAqC,CAAC,OAAO,CAAC,CAAC;QAClE,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,CAAC;IAC7D,CAAC;CACF"}

package/dist/rendering/templates/template-token.interface.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Defines the responsibility of representing parsed template tokens.
+ */
+export interface TemplateToken {
+    /**
+     * Token category to differentiate between reactive bindings, constants, rules, etc.
+     */
+    readonly kind: "binding" | "constant" | "rule" | string;
+    /**
+     * Trimmed value of the token (e.g., property path for bindings).
+     */
+    readonly value: string;
+    /**
+     * Raw substring matched in the template, including delimiters.
+     */
+    readonly raw: string;
+    /**
+     * Inclusive start offset in the template string.
+     */
+    readonly start: number;
+    /**
+     * Exclusive end offset in the template string.
+     */
+    readonly end: number;
+}
+/**
+ * Defines the responsibility of extracting template tokens from a template string.
+ */
+export interface ITemplateTokenExtractor {
+    /**
+     * Extracts tokens from the provided template string.
+     *
+     * @param template - Template source to analyze
+     * @returns List of extracted tokens (may be empty)
+     */
+    extract(template: string): TemplateToken[];
+}
+//# sourceMappingURL=template-token.interface.d.ts.map

package/dist/rendering/templates/template-token.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-token.interface.d.ts","sourceRoot":"","sources":["../../../src/rendering/templates/template-token.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IAExD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAAC;CAC5C"}

package/dist/rendering/templates/template-token.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=template-token.interface.js.map

package/dist/rendering/templates/template-token.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-token.interface.js","sourceRoot":"","sources":["../../../src/rendering/templates/template-token.interface.ts"],"names":[],"mappings":""}

package/dist/types/interfaces.d.ts

@@ -0,0 +1,204 @@
+import { IStateSignal } from "../reactive/signal.js";
+/**
+ * Base interface for all components
+ */
+export interface IComponent {
+    /**
+     * Gets whether the component has been rendered
+     */
+    readonly isRendered: boolean;
+    /**
+     * Gets the root HTML element of the component
+     */
+    readonly htmlElement: HTMLElement;
+    /**
+     * Appends the component to a parent element
+     */
+    setInElement(element: HTMLElement): void;
+    /**
+     * Removes the component from the DOM and cleans up resources
+     */
+    remove(fromDom?: boolean): void;
+}
+/**
+ * Base interface for component initializers
+ *
+ * @description
+ * Defines the contract for asynchronous component initialization.
+ * Initializers are responsible for loading data, setting up dependencies,
+ * and preparing components before rendering.
+ *
+ * @template TComponent - The component type being initialized
+ *
+ * @example
+ * ```typescript
+ * class TodoListInitializer implements IComponentInitializer<TodoListComponent> {
+ *   constructor(private todoService: TodoService) {}
+ *
+ *   async initialize(component: TodoListComponent): Promise<boolean> {
+ *     const todos = await this.todoService.loadTodos();
+ *     component.todos = todos;
+ *     return true; // Success
+ *   }
+ * }
+ * ```
+ */
+export interface IComponentInitializer<TComponent> {
+    /**
+     * Initializes the component with initial data and configuration
+     *
+     * @param component - Component instance to initialize
+     * @returns Promise resolving to true if successful, false otherwise
+     */
+    initialize(component: TComponent): boolean | Promise<boolean>;
+}
+/**
+ * Base interface for lifecycle managers
+ *
+ * @description
+ * Defines the contract for managing component lifecycle, events, and subscriptions.
+ * Lifecycle managers act as mediators between components and services.
+ *
+ * @template TComponent - The component type being managed
+ *
+ * @example
+ * ```typescript
+ * class TodoListLifecycleManager implements ILifecycleManager<TodoListComponent> {
+ *   constructor(private todoService: TodoService) {}
+ *
+ *   startListening(component: TodoListComponent): void {
+ *     // Subscribe to component events
+ *     // Call service methods
+ *     // Update component state
+ *   }
+ *
+ *   stopListening(): void {
+ *     // Cleanup subscriptions
+ *   }
+ *
+ *   dispose(): void {
+ *     // Final cleanup
+ *   }
+ * }
+ * ```
+ */
+export interface ILifecycleManager<TComponent> {
+    /**
+     * The component being managed
+     */
+    readonly component: TComponent | null;
+    /**
+     * Starts listening to events and managing component lifecycle
+     *
+     * @param component - Component instance to manage
+     */
+    startListening(component: TComponent): void;
+    /**
+     * Stops listening to events and cleans up subscriptions
+     */
+    stopListening(): void;
+    /**
+     * Disposes of all resources
+     */
+    dispose(): void;
+}
+/**
+ * Reactive state management interface
+ *
+ * @description
+ * Defines the contract for granular reactive state management.
+ * Each property has its own observable channel for optimal performance.
+ *
+ * @remarks
+ * Implemented by SmartComponent to provide property-specific reactivity.
+ * RenderEngine subscribes to specific properties to avoid unnecessary updates.
+ */
+export interface IReactiveState {
+    /**
+     * Gets or creates property-specific observable for granular reactivity
+     *
+     * @param propName - Name of the property to observe
+     * @returns Observable that emits when the property changes
+     *
+     * @example
+     * ```typescript
+     * // RenderEngine subscribes to specific property
+     * component.getPropertyObservable('count').subscribe(() => {
+     *   // Only runs when 'count' changes
+     *   updateDOM();
+     * });
+     * ```
+     */
+    getPropertyObservable(propName: string): IStateSignal;
+}
+/**
+ * Type for subscription cleanup functions
+ */
+export type SubscriptionCleanup = () => void;
+/**
+ * Metadata for behaviors attached to components
+ *
+ * @description
+ * Stores initializer and lifecycle manager types for component registration.
+ * Used internally by decorators and registration system.
+ */
+export interface BehaviorMetadata {
+    initializerType?: new (...args: unknown[]) => IComponentInitializer<unknown>;
+    lifecycleManagerType?: new (...args: unknown[]) => ILifecycleManager<unknown>;
+}
+/**
+ * HTML5 validation rules for form inputs
+ *
+ * @description
+ * Defines the structure for validation rules that can be automatically
+ * converted to HTML validation attributes using [[RULES.field]] syntax.
+ * Supports all standard HTML5 validation attributes.
+ *
+ * @example
+ * ```typescript
+ * const rules: ValidationRules = {
+ *   username: {
+ *     required: true,
+ *     minlength: 3,
+ *     maxlength: 20,
+ *     pattern: '^[a-zA-Z0-9_]+$'
+ *   },
+ *   email: {
+ *     required: true
+ *   },
+ *   age: {
+ *     min: 18,
+ *     max: 120
+ *   }
+ * };
+ * ```
+ */
+export interface ValidationRules {
+    [fieldName: string]: {
+        /** Makes the field required */
+        required?: boolean;
+        /** Minimum length for text inputs */
+        minlength?: number;
+        /** Maximum length for text inputs */
+        maxlength?: number;
+        /** Regular expression pattern */
+        pattern?: string;
+        /** Minimum value for number/date inputs */
+        min?: number | string;
+        /** Maximum value for number/date inputs */
+        max?: number | string;
+        /** Step increment for number inputs */
+        step?: number | string;
+        /** Accepted file types (for file inputs) */
+        accept?: string;
+        /** Autocomplete behavior */
+        autocomplete?: string;
+        /** Input placeholder text */
+        placeholder?: string;
+        /** Input title/tooltip */
+        title?: string;
+        /** Custom validation message */
+        message?: string;
+    };
+}
+//# sourceMappingURL=interfaces.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/types/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAEzC;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,qBAAqB,CAAC,UAAU;IAC/C;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,iBAAiB,CAAC,UAAU;IAC3C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAEtC;;;;OAIG;IACH,cAAc,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAE5C;;OAEG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;OAcG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,IAAI,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,eAAe,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC7E,oBAAoB,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,iBAAiB,CAAC,OAAO,CAAC,CAAC;CAC/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,SAAS,EAAE,MAAM,GAAG;QACnB,+BAA+B;QAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;QAEnB,qCAAqC;QACrC,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB,qCAAqC;QACrC,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB,iCAAiC;QACjC,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,2CAA2C;QAC3C,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAEtB,2CAA2C;QAC3C,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAEtB,uCAAuC;QACvC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAEvB,4CAA4C;QAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,4BAA4B;QAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;QAEtB,6BAA6B;QAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB,0BAA0B;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;QAEf,gCAAgC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH"}

package/dist/types/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/types/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/types/interfaces.ts"],"names":[],"mappings":""}

package/dist/utils/dom-utils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Creates an HTMLElement from a template string.
+ *
+ * @param template - HTML template string containing a single root element
+ * @returns The parsed HTMLElement from the template
+ * @throws Error if template is empty or does not contain exactly one root element
+ *
+ * @example
+ * ```typescript
+ * const element = createElementFromTemplate('<div class="card"><p>Hello</p></div>');
+ * ```
+ */
+export declare function createElementFromTemplate(template: string): HTMLElement;
+/**
+ * Gets an element by class name within a root element.
+ *
+ * @param root - Root HTMLElement to search within
+ * @param className - CSS class name to match (checked on root and descendants)
+ * @returns The matching HTMLElement, or undefined if not found
+ * @throws Error if root is not provided
+ *
+ * @example
+ * ```typescript
+ * const cardElement = getElementByClass(container, 'card');
+ * ```
+ */
+export declare function getElementByClass(root: HTMLElement, className: string): HTMLElement | undefined;
+/**
+ * Regular expression pattern for matching template placeholders.
+ * Matches `{{propertyName}}` patterns with optional whitespace.
+ *
+ * @example
+ * ```typescript
+ * const matches = text.match(PLACEHOLDER_PATTERN);
+ * // Matches: {{ foo }}, {{bar}}, {{ baz.nested }}
+ * ```
+ */
+export declare const PLACEHOLDER_PATTERN: RegExp;
+/**
+ * Extracts placeholder names from a string.
+ *
+ * @param text - Text to extract placeholders from
+ * @returns Array of placeholder property names without braces
+ *
+ * @example
+ * ```typescript
+ * const names = extractPlaceholders('Hello {{firstName}} {{lastName}}');
+ * // Returns: ['firstName', 'lastName']
+ * ```
+ */
+export declare function extractPlaceholders(text: string): string[];
+/**
+ * Replaces placeholders in a template with actual values.
+ * Supports dot notation for nested properties (e.g. `{{user.name}}`).
+ *
+ * @param template - Template string with placeholders
+ * @param values - Object containing values to substitute
+ * @returns Template string with placeholders replaced by corresponding values
+ * @throws Never - Missing values are replaced with empty strings
+ *
+ * @example
+ * ```typescript
+ * const result = replacePlaceholders('Hello {{name}}!', { name: 'John' });
+ * // Returns: 'Hello John!'
+ *
+ * const nested = replacePlaceholders('{{user.name}}', { user: { name: 'Alice' } });
+ * // Returns: 'Alice'
+ * ```
+ */
+export declare function replacePlaceholders(template: string, values: Record<string, unknown>): string;
+//# sourceMappingURL=dom-utils.d.ts.map

package/dist/utils/dom-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-utils.d.ts","sourceRoot":"","sources":["../../src/utils/dom-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAiBvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAO/F;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,QAAoB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAY1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAoB7F"}

package/dist/utils/dom-utils.js

@@ -0,0 +1,119 @@
+/**
+ * Creates an HTMLElement from a template string.
+ *
+ * @param template - HTML template string containing a single root element
+ * @returns The parsed HTMLElement from the template
+ * @throws Error if template is empty or does not contain exactly one root element
+ *
+ * @example
+ * ```typescript
+ * const element = createElementFromTemplate('<div class="card"><p>Hello</p></div>');
+ * ```
+ */
+export function createElementFromTemplate(template) {
+    // Handle empty or whitespace-only templates
+    const trimmedTemplate = template.trim();
+    if (!trimmedTemplate) {
+        // Return an empty div as fallback
+        return document.createElement('div');
+    }
+    const div = document.createElement('div');
+    div.innerHTML = trimmedTemplate;
+    const element = div.firstElementChild;
+    if (!element || !(element instanceof HTMLElement)) {
+        throw new Error('Template must contain exactly one root element');
+    }
+    return element;
+}
+/**
+ * Gets an element by class name within a root element.
+ *
+ * @param root - Root HTMLElement to search within
+ * @param className - CSS class name to match (checked on root and descendants)
+ * @returns The matching HTMLElement, or undefined if not found
+ * @throws Error if root is not provided
+ *
+ * @example
+ * ```typescript
+ * const cardElement = getElementByClass(container, 'card');
+ * ```
+ */
+export function getElementByClass(root, className) {
+    if (root.classList.contains(className)) {
+        return root;
+    }
+    const element = root.getElementsByClassName(className)[0];
+    return element instanceof HTMLElement ? element : undefined;
+}
+/**
+ * Regular expression pattern for matching template placeholders.
+ * Matches `{{propertyName}}` patterns with optional whitespace.
+ *
+ * @example
+ * ```typescript
+ * const matches = text.match(PLACEHOLDER_PATTERN);
+ * // Matches: {{ foo }}, {{bar}}, {{ baz.nested }}
+ * ```
+ */
+export const PLACEHOLDER_PATTERN = /{{\s*([^}]*)}}/g;
+/**
+ * Extracts placeholder names from a string.
+ *
+ * @param text - Text to extract placeholders from
+ * @returns Array of placeholder property names without braces
+ *
+ * @example
+ * ```typescript
+ * const names = extractPlaceholders('Hello {{firstName}} {{lastName}}');
+ * // Returns: ['firstName', 'lastName']
+ * ```
+ */
+export function extractPlaceholders(text) {
+    const placeholders = [];
+    const matches = text.matchAll(PLACEHOLDER_PATTERN);
+    for (const match of matches) {
+        const propertyName = match[1].trim();
+        if (propertyName) {
+            placeholders.push(propertyName);
+        }
+    }
+    return placeholders;
+}
+/**
+ * Replaces placeholders in a template with actual values.
+ * Supports dot notation for nested properties (e.g. `{{user.name}}`).
+ *
+ * @param template - Template string with placeholders
+ * @param values - Object containing values to substitute
+ * @returns Template string with placeholders replaced by corresponding values
+ * @throws Never - Missing values are replaced with empty strings
+ *
+ * @example
+ * ```typescript
+ * const result = replacePlaceholders('Hello {{name}}!', { name: 'John' });
+ * // Returns: 'Hello John!'
+ *
+ * const nested = replacePlaceholders('{{user.name}}', { user: { name: 'Alice' } });
+ * // Returns: 'Alice'
+ * ```
+ */
+export function replacePlaceholders(template, values) {
+    return template.replace(PLACEHOLDER_PATTERN, (match, expression) => {
+        const trimmed = expression.trim();
+        // Handle dot notation
+        if (trimmed.includes('.')) {
+            const parts = trimmed.split('.');
+            let current = values;
+            for (const part of parts) {
+                if (current === null || current === undefined)
+                    return '';
+                if (typeof current !== 'object')
+                    return '';
+                current = current[part];
+            }
+            return current !== undefined && current !== null ? String(current) : '';
+        }
+        return trimmed in values ? String(values[trimmed]) : match;
+    });
+}
+//# sourceMappingURL=dom-utils.js.map

package/dist/utils/dom-utils.js.map

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