@jasonshimmy/custom-elements-runtime 0.3.1 → 1.0.0

package/dist/index.d.ts

@@ -1,16 +1,18 @@
 /**
  * Custom Elements Runtime
  * Lightweight, strongly typed, functional custom element runtime for two-way binding, event, and prop support.
- * Supports: state, computed, props, style, render, lifecycle hooks, :model and @event attributes.
+ * Supports: reactive props, computed, events, style, render, lifecycle hooks, :model and @event attributes.
  * No external dependencies. Mobile-first, secure, and developer friendly.
  */
-export * from "./runtime/types";
+export { component } from "./runtime/component";
+export { useEmit, useOnConnected, useOnDisconnected, useOnAttributeChanged, useOnError, useStyle } from "./runtime/hooks";
+export { ref, computed, watch } from "./runtime/reactive";
+export { html } from "./runtime/template-compiler";
+export { css } from "./runtime/style";
+export { renderToString } from "./runtime/vdom";
+export type { VNode } from "./runtime/types";
 export * from "./directives";
 export * from "./directive-enhancements";
 export * from "./event-bus";
 export * from "./store";
 export * from "./router";
-export { renderToString } from "./runtime/vdom";
-export { component } from "./runtime/component";
-export { css } from "./runtime/style";
-export { html } from "./runtime/template-compiler";

package/dist/runtime/component.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentConfig, ComponentContext } from "./types";
+import type { ComponentConfig, VNode } from "./types";
 /**
  * @internal
  * Runtime registry of component configs.
@@ -7,7 +7,44 @@ import type { ComponentConfig, ComponentContext } from "./types";
  * internal tests only. Consumers should use the public `component` API.
  */
 export declare const registry: Map<string, ComponentConfig<any, any, any>>;
-export declare function component<S extends object = {}, C extends object = {}, P extends object = {}, T extends object = any>(tag: string, renderOrConfig: ((context: ComponentContext<S, C, P, T>) => any) | ComponentConfig<S, C, P, T>, config?: Partial<ComponentConfig<S, C, P, T>>): void;
 export declare function createElementClass<S extends object, C extends object, P extends object, T extends object = any>(tag: string, config: ComponentConfig<S, C, P, T>): CustomElementConstructor | {
     new (): object;
 };
+/**
+ * Streamlined functional component API with automatic reactive props and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * // Simple component with no parameters
+ * component('simple-header', () => {
+ *   return html`<h1>Hello World</h1>`;
+ * });
+ *
+ * // With props only
+ * component('with-props', ({ message = 'Hello' }) => {
+ *   return html`<div>${message}</div>`;
+ * });
+ *
+ * // With props and hooks
+ * component('my-switch', ({
+ *   modelValue = false,
+ *   label = ''
+ * }, { emit, onConnected, onDisconnected }) => {
+ *   onConnected(() => console.log('Switch connected!'));
+ *   onDisconnected(() => console.log('Switch disconnected!'));
+ *
+ *   return html`
+ *     <label>
+ *       ${label}
+ *       <input
+ *         type="checkbox"
+ *         :checked="${modelValue}"
+ *         @change="${(e) => emit('update:modelValue', e.target.checked)}"
+ *       />
+ *     </label>
+ *   `;
+ * });
+ * ```
+ */
+export declare function component(tag: string, renderFn: () => VNode | VNode[] | Promise<VNode | VNode[]>): void;
+export declare function component<TProps extends Record<string, any> = {}>(tag: string, renderFn: (props: TProps) => VNode | VNode[] | Promise<VNode | VNode[]>): void;

package/dist/runtime/event-manager.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Event Manager for tracking and cleaning up event listeners
+ * Prevents memory leaks by maintaining cleanup functions
+ */
+/**
+ * Manages event listeners and their cleanup for elements
+ */
+declare class EventManager {
+    private static cleanupFunctions;
+    /**
+     * Add an event listener with automatic cleanup tracking
+     */
+    static addListener(element: HTMLElement, event: string, handler: EventListener, options?: AddEventListenerOptions): void;
+    /**
+     * Remove a specific event listener
+     */
+    static removeListener(element: HTMLElement, event: string, handler: EventListener, options?: EventListenerOptions): void;
+    /**
+     * Clean up all event listeners for an element
+     */
+    static cleanup(element: HTMLElement): void;
+    /**
+     * Clean up all tracked event listeners (useful for testing)
+     */
+    static cleanupAll(): void;
+    /**
+     * Check if an element has any tracked event listeners
+     */
+    static hasListeners(element: HTMLElement): boolean;
+    /**
+     * Get the number of tracked event listeners for an element
+     */
+    static getListenerCount(element: HTMLElement): number;
+}
+/**
+ * Enhanced event listener tracker that stores more metadata
+ * for better debugging and cleanup
+ */
+interface EventListenerMetadata {
+    event: string;
+    handler: EventListener;
+    options?: AddEventListenerOptions;
+    cleanup: () => void;
+    addedAt: number;
+}
+declare class DetailedEventManager {
+    private static listeners;
+    static addListener(element: HTMLElement, event: string, handler: EventListener, options?: AddEventListenerOptions): void;
+    static removeListener(element: HTMLElement, event: string, handler: EventListener, options?: EventListenerOptions): boolean;
+    static cleanup(element: HTMLElement): void;
+    static getListenerInfo(element: HTMLElement): EventListenerMetadata[];
+    static findStaleListeners(_maxAge?: number): Array<{
+        element: HTMLElement;
+        listeners: EventListenerMetadata[];
+    }>;
+}
+export { EventManager, DetailedEventManager };
+export type { EventListenerMetadata };

package/dist/runtime/helpers.d.ts

@@ -1,4 +1,23 @@
+/**
+ * Convert camelCase to kebab-case with caching
+ */
 export declare function toKebab(str: string): string;
+/**
+ * Convert kebab-case to camelCase with caching
+ */
+export declare function toCamel(str: string): string;
+/**
+ * Clear string transformation caches (useful for testing)
+ */
+export declare function clearStringCaches(): void;
+/**
+ * Get cache statistics for debugging
+ */
+export declare function getStringCacheStats(): {
+    kebabCacheSize: number;
+    camelCacheSize: number;
+    htmlEscapeCacheSize: number;
+};
 export declare function escapeHTML(str: string | number | boolean): string | number | boolean;
 /**
  * Get nested property value from object using dot notation

package/dist/runtime/hooks.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Context-based hooks for functional components
+ * Provides React-like hooks with perfect TypeScript inference
+ */
+/**
+ * Set the current component context (called internally during render)
+ * @internal
+ */
+export declare function setCurrentComponentContext(context: any): void;
+/**
+ * Clear the current component context (called internally after render)
+ * @internal
+ */
+export declare function clearCurrentComponentContext(): void;
+/**
+ * Get the emit function for the current component
+ * Must be called during component render
+ *
+ * @example
+ * ```ts
+ * component('my-button', ({ label = 'Click me' }) => {
+ *   const emit = useEmit();
+ *
+ *   return html`
+ *     <button @click="${() => emit('button-click', { label })}">
+ *       ${label}
+ *     </button>
+ *   `;
+ * });
+ * ```
+ */
+export declare function useEmit(): (eventName: string, detail?: any) => boolean;
+/**
+ * Register a callback to be called when component is connected to DOM
+ *
+ * @example
+ * ```ts
+ * component('my-component', () => {
+ *   useOnConnected(() => {
+ *     console.log('Component mounted!');
+ *   });
+ *
+ *   return html`<div>Hello World</div>`;
+ * });
+ * ```
+ */
+export declare function useOnConnected(callback: () => void): void;
+/**
+ * Register a callback to be called when component is disconnected from DOM
+ *
+ * @example
+ * ```ts
+ * component('my-component', () => {
+ *   useOnDisconnected(() => {
+ *     console.log('Component unmounted!');
+ *   });
+ *
+ *   return html`<div>Goodbye World</div>`;
+ * });
+ * ```
+ */
+export declare function useOnDisconnected(callback: () => void): void;
+/**
+ * Register a callback to be called when an attribute changes
+ *
+ * @example
+ * ```ts
+ * component('my-component', () => {
+ *   useOnAttributeChanged((name, oldValue, newValue) => {
+ *     console.log(`Attribute ${name} changed from ${oldValue} to ${newValue}`);
+ *   });
+ *
+ *   return html`<div>Attribute watcher</div>`;
+ * });
+ * ```
+ */
+export declare function useOnAttributeChanged(callback: (name: string, oldValue: string | null, newValue: string | null) => void): void;
+/**
+ * Register a callback to be called when an error occurs
+ *
+ * @example
+ * ```ts
+ * component('my-component', () => {
+ *   useOnError((error) => {
+ *     console.error('Component error:', error);
+ *   });
+ *
+ *   return html`<div>Error handler</div>`;
+ * });
+ * ```
+ */
+export declare function useOnError(callback: (error: Error) => void): void;
+/**
+ * Register a style function that will be called during each render
+ * to provide reactive styles for the component
+ *
+ * @example
+ * ```ts
+ * import { css } from '@lib/style';
+ *
+ * component('my-component', ({ theme = 'light' }) => {
+ *   useStyle(() => css`
+ *     :host {
+ *       background: ${theme === 'light' ? 'white' : 'black'};
+ *       color: ${theme === 'light' ? 'black' : 'white'};
+ *     }
+ *   `);
+ *
+ *   return html`<div>Styled component</div>`;
+ * });
+ * ```
+ */
+export declare function useStyle(callback: () => string): void;

package/dist/runtime/props.d.ts

@@ -1,6 +1,18 @@
 import type { ComponentConfig, ComponentContext } from "./types";
+export type PropDefinition = {
+    type: StringConstructor | NumberConstructor | BooleanConstructor | FunctionConstructor;
+    default?: string | number | boolean;
+};
 /**
- * Applies props to the component context.
+ * Applies props to the component context using a direct prop definitions object.
+ * @param element - The custom element instance.
+ * @param propDefinitions - Object mapping prop names to their definitions.
+ * @param context - The component context.
+ */
+export declare function applyPropsFromDefinitions(element: HTMLElement, propDefinitions: Record<string, PropDefinition>, context: any): void;
+/**
+ * Legacy function for ComponentConfig compatibility.
+ * Applies props to the component context using a ComponentConfig.
  * @param element - The custom element instance.
  * @param cfg - The component config.
  * @param context - The component context.

package/dist/runtime/reactive-proxy-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Reactive proxy cache to optimize proxy creation and reuse
+ * Uses WeakMap for automatic garbage collection when objects are no longer referenced
+ */
+declare class ReactiveProxyCache {
+    private static cache;
+    private static arrayHandlerCache;
+    private static objectHandlerCache;
+    /**
+     * Get or create a reactive proxy for an object
+     */
+    static getOrCreateProxy<T extends object>(obj: T, reactiveState: any, isArray?: boolean): T;
+    /**
+     * Get or create a cached array handler
+     */
+    private static getOrCreateArrayHandler;
+    /**
+     * Get or create a cached object handler
+     */
+    private static getOrCreateObjectHandler;
+    /**
+     * Check if an object already has a cached proxy
+     */
+    static hasProxy(obj: object): boolean;
+    /**
+     * Clear all cached proxies (useful for testing)
+     */
+    static clear(): void;
+    /**
+     * Get cache statistics (for debugging)
+     * Note: WeakMap doesn't provide size, so this is limited
+     */
+    static getStats(): {
+        hasCachedProxies: boolean;
+    };
+}
+/**
+ * Optimized proxy creation utilities
+ */
+declare class ProxyOptimizer {
+    private static contextCache;
+    /**
+     * Create an optimized reactive proxy with minimal overhead
+     */
+    static createReactiveProxy<T extends object>(obj: T, onUpdate: () => void, makeReactive: (value: any) => any): T;
+    /**
+     * Mark an object as a proxy (for optimization)
+     */
+    static markAsProxy(obj: any): void;
+}
+export { ReactiveProxyCache, ProxyOptimizer };

package/dist/runtime/reactive.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Global reactive system for tracking dependencies and triggering updates
+ */
+declare class ReactiveSystem {
+    private currentComponent;
+    private componentDependencies;
+    private componentRenderFunctions;
+    private stateStorage;
+    private stateIndexCounter;
+    private trackingDisabled;
+    private lastWarningTime;
+    /**
+     * Set the current component being rendered for dependency tracking
+     */
+    setCurrentComponent(componentId: string, renderFn: () => void): void;
+    /**
+     * Clear the current component after rendering
+     */
+    clearCurrentComponent(): void;
+    /**
+     * Temporarily disable dependency tracking
+     */
+    disableTracking(): void;
+    /**
+     * Re-enable dependency tracking
+     */
+    enableTracking(): void;
+    /**
+     * Check if a component is currently rendering
+     */
+    isRenderingComponent(): boolean;
+    /**
+     * Return whether we should emit a render-time warning for the current component.
+     * This throttles warnings to avoid spamming the console for legitimate rapid updates.
+     */
+    shouldEmitRenderWarning(): boolean;
+    /**
+     * Execute a function with tracking disabled
+     */
+    withoutTracking<T>(fn: () => T): T;
+    /**
+     * Get or create a state instance for the current component
+     */
+    getOrCreateState<T>(initialValue: T): ReactiveState<T>;
+    /**
+     * Track a dependency for the current component
+     */
+    trackDependency(state: ReactiveState<any>): void;
+    /**
+     * Trigger updates for all components that depend on a state
+     */
+    triggerUpdate(state: ReactiveState<any>): void;
+    /**
+     * Clean up component dependencies when component is destroyed
+     */
+    cleanup(componentId: string): void;
+}
+declare const reactiveSystem: ReactiveSystem;
+export { reactiveSystem };
+/**
+ * Internal reactive state class
+ */
+export declare class ReactiveState<T> {
+    private _value;
+    private dependents;
+    constructor(initialValue: T);
+    get value(): T;
+    set value(newValue: T);
+    addDependent(componentId: string): void;
+    removeDependent(componentId: string): void;
+    getDependents(): Set<string>;
+    private makeReactive;
+}
+/**
+ * Create reactive state that automatically triggers component re-renders
+ * when accessed during render and modified afterwards.
+ * Defaults to null if no initial value is provided (Vue-style ref).
+ *
+ * @example
+ * ```ts
+ * const counter = ref(0);
+ * const user = ref({ name: 'John', age: 30 });
+ * const emptyRef = ref(); // defaults to null
+ *
+ * // Usage in component
+ * counter.value++; // triggers re-render
+ * user.value.name = 'Jane'; // triggers re-render
+ * console.log(emptyRef.value); // null
+ * ```
+ */
+export declare function ref<T = null>(initialValue?: T): ReactiveState<T extends undefined ? null : T>;
+/**
+ * Create computed state that derives from other reactive state
+ *
+ * @example
+ * ```ts
+ * const firstName = ref('John');
+ * const lastName = ref('Doe');
+ * const fullName = computed(() => `${firstName.value} ${lastName.value}`);
+ * ```
+ */
+export declare function computed<T>(fn: () => T): {
+    readonly value: T;
+};
+/**
+ * Create a watcher that runs when dependencies change
+ *
+ * @example
+ * ```ts
+ * const count = ref(0);
+ * watch(() => count.value, (newVal, oldVal) => {
+ *   console.log(`Count changed from ${oldVal} to ${newVal}`);
+ * });
+ * ```
+ */
+export declare function watch<T>(source: () => T, callback: (newValue: T, oldValue: T) => void, options?: {
+    immediate?: boolean;
+}): () => void;

package/dist/runtime/render.d.ts

@@ -9,10 +9,10 @@ export declare function renderComponent<S extends object, C extends object, P ex
  */
 export declare function renderOutput<S extends object, C extends object, P extends object, T extends object>(shadowRoot: ShadowRoot | null, output: VNode | VNode[], context: ComponentContext<S, C, P, T>, refs: Refs["refs"], setHtmlString: (html: string) => void): void;
 /**
- * Debounced render request.
+ * Debounced render request with infinite loop protection.
  */
 export declare function requestRender(renderFn: () => void, lastRenderTime: number, renderCount: number, setLastRenderTime: (t: number) => void, setRenderCount: (c: number) => void, renderTimeoutId: ReturnType<typeof setTimeout> | null, setRenderTimeoutId: (id: ReturnType<typeof setTimeout> | null) => void): void;
 /**
  * Applies styles to the shadowRoot.
  */
-export declare function applyStyle<S extends object, C extends object, P extends object, T extends object>(shadowRoot: ShadowRoot | null, cfg: ComponentConfig<S, C, P, T>, context: ComponentContext<S, C, P, T>, htmlString: string, styleSheet: CSSStyleSheet | null, setStyleSheet: (sheet: CSSStyleSheet | null) => void): void;
+export declare function applyStyle<S extends object, C extends object, P extends object, T extends object>(shadowRoot: ShadowRoot | null, context: ComponentContext<S, C, P, T>, htmlString: string, styleSheet: CSSStyleSheet | null, setStyleSheet: (sheet: CSSStyleSheet | null) => void): void;

package/dist/runtime/secure-expression-evaluator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Secure expression evaluator to replace unsafe Function() constructor
+ * Provides AST-based validation and caching for performance
+ */
+/**
+ * Secure expression evaluator with caching and AST validation
+ */
+declare class SecureExpressionEvaluator {
+    private static cache;
+    private static maxCacheSize;
+    private static dangerousPatterns;
+    static evaluate(expression: string, context: any): any;
+    private static createEvaluator;
+    private static hasDangerousPatterns;
+    private static createSafeEvaluator;
+    private static createObjectEvaluator;
+    private static parseObjectProperties;
+    private static createSimpleEvaluator;
+    /**
+     * Evaluate a very small, safe expression grammar without using eval/Function.
+     * Supports: numbers, string literals, true/false, null, arrays, unary !,
+     * arithmetic (+ - * / %), comparisons, logical && and ||, parentheses, and ternary `a ? b : c`.
+     */
+    private static evaluateBasicExpression;
+    private static tokenize;
+    private static evaluateSimpleValue;
+    static clearCache(): void;
+    static getCacheSize(): number;
+}
+export { SecureExpressionEvaluator };

package/dist/runtime/template-compiler.d.ts

@@ -23,6 +23,10 @@ export declare function parseProps(str: string, values?: unknown[], context?: Re
  *  - Do not rewrap interpolated VNodes (preserve their keys); only fill in missing keys.
  */
 export declare function htmlImpl(strings: TemplateStringsArray, values: unknown[], context?: Record<string, any>): VNode | VNode[];
+/**
+ * Clear the template compile cache (useful for tests)
+ */
+export declare function clearTemplateCompileCache(): void;
 /**
  * Default export: plain html.
  */

package/dist/runtime/types.d.ts

@@ -14,6 +14,7 @@ export interface VNode {
             arg?: string;
         }>;
         ref?: string;
+        reactiveRef?: any;
         /** Compiler-provided hint: whether this VNode represents a custom element (contains a dash) */
         isCustomElement?: boolean;
     };
@@ -30,7 +31,7 @@ export interface AnchorBlockVNode extends VNode {
 /**
  * Runtime types
  */
-export type LifecycleKeys = "onConnected" | "onDisconnected" | "onAttributeChanged" | "onError" | "errorFallback";
+export type LifecycleKeys = "onConnected" | "onDisconnected" | "onAttributeChanged" | "onError";
 export interface WatchOptions {
     immediate?: boolean;
     deep?: boolean;
@@ -64,24 +65,15 @@ export type ComponentContext<S extends object, C extends object, P extends objec
     emit: <D = any>(eventName: string, detail?: D, options?: CustomEventInit) => boolean;
 };
 export type ComponentConfig<S extends object, C extends object = {}, P extends object = {}, T extends object = {}> = {
-    state?: S;
-    computed?: {
-        [K in keyof C]: (context: ComponentContext<S, C, P, T>) => C[K];
-    };
     props?: Record<string, {
         type: StringConstructor | NumberConstructor | BooleanConstructor | FunctionConstructor;
         default?: string | number | boolean;
     }>;
-    watch?: WatchConfig<ComponentContext<S, C, P, T>>;
-    style?: string | ((context: ComponentContext<S, C, P, T>) => string);
     render: (context: ComponentContext<S, C, P, T>) => VNode | VNode[] | Promise<VNode | VNode[]>;
-    loadingTemplate?: (context: ComponentContext<S, C, P, T>) => VNode | VNode[];
-    errorTemplate?: (error: Error, context: ComponentContext<S, C, P, T>) => VNode | VNode[];
     onConnected?: (context: ComponentContext<S, C, P, T>) => void;
     onDisconnected?: (context: ComponentContext<S, C, P, T>) => void;
     onAttributeChanged?: (name: string, oldValue: string | null, newValue: string | null, context: ComponentContext<S, C, P, T>) => void;
     onError?: (error: Error | null, context: ComponentContext<S, C, P, T>) => void;
-    errorFallback?: (error: Error | null, context: ComponentContext<S, C, P, T>) => string;
 } & {
     [K in keyof T as K extends LifecycleKeys ? never : K]: T[K] extends Function ? T[K] : never;
 };

package/dist/runtime/vdom.d.ts

@@ -5,7 +5,7 @@
  */
 import type { VNode, VDomRefs } from "./types";
 /**
- * Recursively clean up refs for all descendants of a node
+ * Recursively clean up refs and event listeners for all descendants of a node
  * @param node The node to clean up.
  * @param refs The refs to clean up.
  * @returns
@@ -22,7 +22,7 @@ export declare function cleanupRefs(node: Node, refs?: VDomRefs): void;
  * @param el
  * @returns
  */
-export declare function processModelDirective(value: string, modifiers: string[], props: Record<string, any>, attrs: Record<string, any>, listeners: Record<string, EventListener>, context?: any, el?: HTMLElement, arg?: string): void;
+export declare function processModelDirective(value: string | any, modifiers: string[], props: Record<string, any>, attrs: Record<string, any>, listeners: Record<string, EventListener>, context?: any, el?: HTMLElement, arg?: string): void;
 /**
  * Process :bind directive for attribute/property binding
  * @param value
@@ -49,6 +49,14 @@ export declare function processClassDirective(value: any, attrs: Record<string,
  * @returns
  */
 export declare function processStyleDirective(value: any, attrs: Record<string, any>, context?: any): void;
+/**
+ * Process :ref directive for element references
+ * @param value
+ * @param props
+ * @param context
+ * @returns
+ */
+export declare function processRefDirective(value: any, props: Record<string, any>, context?: any): void;
 /**
  * Process directives and return merged props, attrs, and event listeners
  * @param directives

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jasonshimmy/custom-elements-runtime",
   "description": "A powerful, modern, and lightweight runtime for creating reactive web components with TypeScript",
-  "version": "0.3.1",
+  "version": "1.0.0",
   "type": "module",
   "keywords": [
     "web-components",