@jasonshimmy/custom-elements-runtime 0.0.1-beta.0

package/dist/data-binding.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Minimal controlled input binding helper for data-model attributes.
+ * Handles checkboxes, radios, text, and modifiers (trim, number).
+ * @param el - Input/select/textarea element
+ * @param stateObj - State object to bind
+ * @param keyWithModifiers - Key and optional modifiers (e.g. 'name|trim|number')
+ */
+export declare function useDataModel<T extends Record<string, unknown>>(el: Element, stateObj: T, keyWithModifiers: string): void;

package/dist/dev-tools.d.ts

@@ -0,0 +1,21 @@
+export declare const DevPerformance: {
+    measureRender<T>(name: string, fn: () => T): T;
+    getMemoryInfo(): any;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    group(...args: unknown[]): void;
+    groupEnd(): void;
+};
+export declare const DevTools: {
+    startTiming(_componentName: string): () => number;
+    inspectComponent(element: HTMLElement): any;
+    trackStateChanges(element: HTMLElement, callback: (changes: any) => void): () => void;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    group(...args: unknown[]): void;
+    groupEnd(): void;
+};

package/dist/event-bus.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Event handler type for global event bus
+ */
+export type EventHandler<T = any> = (data: T) => void;
+/**
+ * GlobalEventBus provides a singleton event bus for cross-component communication.
+ * Uses Set for handler storage to optimize add/remove operations and prevent duplicates.
+ */
+export declare class GlobalEventBus extends EventTarget {
+    private handlers;
+    private static instance;
+    private eventCounters;
+    /**
+     * Returns the singleton instance of GlobalEventBus
+     */
+    static getInstance(): GlobalEventBus;
+    /**
+     * Emit a global event with optional data. Includes event storm protection.
+     * @param eventName - Name of the event
+     * @param data - Optional event payload
+     */
+    emit<T = any>(eventName: string, data?: T): void;
+    /**
+     * Register a handler for a global event. Returns an unsubscribe function.
+     * @param eventName - Name of the event
+     * @param handler - Handler function
+     */
+    on<T = any>(eventName: string, handler: EventHandler<T>): () => void;
+    /**
+     * Remove a specific handler for a global event.
+     * @param eventName - Name of the event
+     * @param handler - Handler function to remove
+     */
+    off<T = any>(eventName: string, handler: EventHandler<T>): void;
+    /**
+     * Remove all handlers for a specific event.
+     * @param eventName - Name of the event
+     */
+    offAll(eventName: string): void;
+    /**
+     * Listen for a native CustomEvent. Returns an unsubscribe function.
+     * @param eventName - Name of the event
+     * @param handler - CustomEvent handler
+     * @param options - AddEventListener options
+     */
+    listen<T = any>(eventName: string, handler: (event: CustomEvent<T>) => void, options?: AddEventListenerOptions): () => void;
+    /**
+     * Register a one-time event handler. Returns a promise that resolves with the event data.
+     * @param eventName - Name of the event
+     * @param handler - Handler function
+     */
+    once<T = any>(eventName: string, handler: EventHandler<T>): Promise<T>;
+    /**
+     * Get a list of all active event names with registered handlers.
+     */
+    getActiveEvents(): string[];
+    /**
+     * Clear all event handlers (useful for testing or cleanup).
+     */
+    clear(): void;
+    /**
+     * Get the number of handlers registered for a specific event.
+     * @param eventName - Name of the event
+     */
+    getHandlerCount(eventName: string): number;
+    /**
+     * Get event statistics for debugging.
+     */
+    getEventStats(): Record<string, {
+        count: number;
+        handlersCount: number;
+    }>;
+    /**
+     * Reset event counters (useful for testing or after resolving issues).
+     */
+    resetEventCounters(): void;
+}
+/**
+ * Singleton instance of the global event bus
+ */
+export declare const eventBus: GlobalEventBus;
+/**
+ * Emit a global event
+ */
+export declare const emit: <T = any>(eventName: string, data?: T) => void;
+/**
+ * Register a handler for a global event
+ */
+export declare const on: <T = any>(eventName: string, handler: EventHandler<T>) => () => void;
+/**
+ * Remove a handler for a global event
+ */
+export declare const off: <T = any>(eventName: string, handler: EventHandler<T>) => void;
+/**
+ * Register a one-time handler for a global event
+ */
+export declare const once: <T = any>(eventName: string, handler: EventHandler<T>) => Promise<T>;
+/**
+ * Listen for a native CustomEvent
+ */
+export declare const listen: <T = any>(eventName: string, handler: (event: CustomEvent<T>) => void, options?: AddEventListenerOptions) => () => void;

package/dist/runtime.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Represents the state object for a component.
+ * Extend this interface for custom state typing.
+ */
+export interface ComponentState extends Record<string, unknown> {
+}
+/**
+ * API exposed to component templates and lifecycle handlers.
+ * Includes state, event emitters, and global event bus methods.
+ */
+export interface ComponentAPI<T extends ComponentState = ComponentState> {
+    /**
+     * Reactive state object. Mutate directly for reactivity.
+     */
+    readonly state: T;
+    emit(eventName: string, detail?: unknown): void;
+    onGlobal<U = any>(eventName: string, handler: (data: U) => void): () => void;
+    offGlobal<U = any>(eventName: string, handler: (data: U) => void): void;
+    emitGlobal<U = any>(eventName: string, data?: U): void;
+}
+/**
+ * Configuration object for a custom element component.
+ * Defines template, state, computed properties, styles, refs, and lifecycle hooks.
+ * @template S - State type
+ * @template C - Computed type
+ */
+export interface ComponentConfig<S extends ComponentState, C extends Record<string, any> = {}> {
+    readonly template: (state: S & C, api: ComponentAPI<S & C>) => string | Promise<string> | CompiledTemplate<S & C>;
+    readonly state: S;
+    readonly computed?: {
+        [K in keyof C]: (state: S) => C[K];
+    };
+    readonly style?: string | ((state: S & C) => string);
+    readonly refs?: Record<string, RefHandler<S & C>>;
+    readonly onMounted?: LifecycleHandler<S & C>;
+    readonly onUnmounted?: LifecycleHandler<S & C>;
+    readonly debug?: boolean;
+    /**
+     * Whitelist of state keys to reflect as attributes. If omitted, no keys are reflected.
+     */
+    readonly reflect?: string[];
+    hydrate?: (el: Element | ShadowRoot, state: S & C, api: ComponentAPI<S & C>) => void;
+    [handler: string]: ((...args: unknown[]) => unknown) | unknown;
+}
+/**
+ * Handler for a ref element in the template.
+ * @param element - The DOM element with data-ref
+ * @param state - Current component state
+ * @param api - Component API
+ */
+export type RefHandler<T extends ComponentState> = (element: Element, state: T, api: ComponentAPI<T>) => void;
+export type ComputedHandler<T extends ComponentState> = (state: T) => unknown;
+/**
+ * Lifecycle handler for mounted/unmounted events.
+ * @param state - Current component state
+ * @param api - Component API
+ */
+export type LifecycleHandler<T extends ComponentState> = (state: T, api: ComponentAPI<T>) => void;
+/**
+ * Represents a compiled template for fast rendering and hydration.
+ */
+export type CompiledTemplate<S extends ComponentState = ComponentState> = {
+    id: string;
+    render: (state: S, api: ComponentAPI<S>) => DocumentFragment;
+};
+/**
+ * Plugin interface for runtime hooks (init, render, error).
+ */
+export type RuntimePlugin<S extends ComponentState, C extends Record<string, any>> = {
+    onInit?: (config: ComponentConfig<S, C>) => void;
+    onRender?: (state: S & C, api: ComponentAPI<S & C>) => void;
+    onError?: (error: Error, state: S & C, api: ComponentAPI<S & C>) => void;
+};
+export declare const runtimePlugins: RuntimePlugin<ComponentState, Record<string, unknown>>[];
+/**
+ * Registers a runtime plugin for hooks (init, render, error).
+ * @param plugin - RuntimePlugin instance
+ */
+export declare function useRuntimePlugin<S extends ComponentState, C extends Record<string, any>>(plugin: RuntimePlugin<S, C>): void;
+export { Store } from './store';
+export { eventBus } from './event-bus';
+export { renderToString, renderComponentsToString, generateHydrationScript } from './ssr';
+export type { SSRComponentConfig, SSRRenderOptions, SSRContext } from './ssr';
+export { html, compile, css, classes, styles, ref, on } from './template-helpers';
+export { useDataModel } from './data-binding';
+export { compileTemplate, renderCompiledTemplate, updateCompiledTemplate } from './template-compiler';
+export { mountVNode, patchVNode, createVNodeFromElement, parseVNodeFromHTML, safeReplaceChild, getVNodeKey } from './v-dom';
+export type { VNode } from './v-dom';
+/**
+ * Recursively sanitizes an object, removing dangerous keys and prototype pollution.
+ * Handles circular references using a WeakSet.
+ * @param obj - Object to sanitize
+ * @param seen - WeakSet to track visited objects
+ */
+export declare function deepSanitizeObject<T>(obj: T, seen?: WeakSet<object>): T;
+/**
+ * Type guard to check if a value is Promise-like.
+ */
+export declare function isPromise(val: unknown): val is Promise<unknown>;
+/**
+ * Registers a new custom element component.
+ * Validates config, sets up reactive state, and defines the custom element.
+ * Supports HMR and SSR hydration.
+ * @template S - State type
+ * @template C - Computed type
+ * @param tag - Custom element tag name
+ * @param config - Component configuration
+ */
+export declare function component<S extends ComponentState, C extends Record<string, any> = {}>(tag: string, config: ComponentConfig<S, C>): void;

package/dist/ssr.d.ts

@@ -0,0 +1,49 @@
+import type { ComponentAPI, ComponentState } from './runtime';
+export interface SSRComponentConfig<T extends ComponentState = ComponentState> {
+    readonly tag: string;
+    readonly template: (state: T, api: ComponentAPI<T>) => string;
+    /**
+     * State object can include computed properties as getter functions that accept state as a parameter.
+     */
+    readonly state: T;
+    readonly style?: string | ((state: T) => string);
+    readonly attrs?: Record<string, string>;
+}
+export interface SSRRenderOptions {
+    /** Include component styles in the output */
+    includeStyles?: boolean;
+    /** Pretty print the HTML output */
+    prettyPrint?: boolean;
+    /** Custom attribute sanitization function */
+    sanitizeAttributes?: (attrs: Record<string, string>) => Record<string, string>;
+}
+export interface SSRContext {
+    /** Track rendered components for hydration */
+    components: Map<string, SSRComponentConfig>;
+    /** Global styles collected during SSR */
+    styles: Set<string>;
+}
+/**
+ * Create a minimal API for SSR that doesn't rely on DOM
+ */
+export declare function createSSRAPI<T extends ComponentState>(state: T): ComponentAPI<T>;
+/**
+ * Render a component to HTML string on the server
+ * This function is treeshakable - only included when imported
+ */
+export declare function renderToString<T extends ComponentState>(config: SSRComponentConfig<T>, options?: SSRRenderOptions): string;
+/**
+ * Render multiple components to HTML with shared context
+ */
+export declare function renderComponentsToString(components: SSRComponentConfig<any>[], options?: SSRRenderOptions): {
+    html: string;
+    styles: string;
+    context: SSRContext;
+};
+/**
+ * Generate hydration script for client-side takeover
+ */
+export declare function generateHydrationScript(context: SSRContext): string;
+export declare const escapeHTML: (str: string) => string;
+export declare const escapeAttribute: (str: string) => string;
+export declare const formatHTML: (html: string) => string;

package/dist/store.d.ts

@@ -0,0 +1,10 @@
+type Listener<T> = (state: T) => void;
+export declare class Store<T extends object> {
+    private state;
+    private listeners;
+    constructor(initial: T);
+    subscribe(listener: Listener<T>): void;
+    getState(): T;
+    private notify;
+}
+export {};

package/dist/template-compiler.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Template Compiler for Custom Elements Runtime
+ *
+ * Provides compile-time template optimization for better runtime performance.
+ * Features:
+ * - Static/dynamic separation
+ * - Efficient DOM updates
+ * - Treeshakable
+ * - TypeScript-friendly
+ * - Development-friendly fallbacks
+ */
+export interface CompiledTemplate<T = any> {
+    /** Static HTML parts that never change */
+    readonly statics: readonly string[];
+    /** Dynamic update functions for each interpolation */
+    readonly dynamics: readonly UpdateFunction<T>[];
+    /** Pre-compiled DOM fragment for initial render */
+    readonly fragment: DocumentFragment | null;
+    /** Unique template ID for caching */
+    readonly id: string;
+    /** Whether this template has dynamic content */
+    readonly hasDynamics: boolean;
+    /** Render method supporting async output */
+    render: (state: T, api: any) => string | Promise<string>;
+}
+export interface UpdateFunction<T = any> {
+    /** Target node path from root (e.g., [0, 1] means first child's second child) */
+    readonly path: readonly number[];
+    /** Type of update (text, attribute, property, etc.) */
+    readonly type: UpdateType;
+    /** Target property/attribute name (for non-text updates) */
+    readonly target?: string;
+    /** Function to extract value from state */
+    readonly getValue: (state: T, api: any) => unknown;
+}
+export type UpdateType = 'text' | 'attribute' | 'property' | 'event' | 'class' | 'style';
+export interface TemplateCompilerOptions {
+    /** Enable development mode with better error messages */
+    development?: boolean;
+    /** Cache compiled templates */
+    cache?: boolean;
+    /** Enable static analysis optimizations */
+    optimize?: boolean;
+}
+/**
+ * Compile a template string into an optimized template object
+ * This is meant to be used at build time for best performance
+ */
+export declare function compileTemplate<T = any>(templateString: string, options?: TemplateCompilerOptions): CompiledTemplate<T>;
+/**
+ * Tagged template literal for compile-time optimization
+ * Usage: compile`<div>${state.name}</div>`
+ */
+/**
+ * Find the DOM path to a placeholder in the template HTML
+ */
+export declare function findDOMPath(templateHTML: string, placeholder: string): number[];
+export declare function compile<T = any>(strings: TemplateStringsArray, ...expressions: Array<(state: T, api: any) => unknown>): CompiledTemplate<T>;
+export declare function parseAndCompileTemplate<T>(template: string, options: {
+    development: boolean;
+    optimize: boolean;
+}): CompiledTemplate<T>;
+export declare class TemplateAnalyzer {
+    private readonly template;
+    private readonly options;
+    private readonly dynamics;
+    private statics;
+    constructor(template: string, options: {
+        development: boolean;
+        optimize: boolean;
+    });
+    compile<T>(): CompiledTemplate<T>;
+    private parseTemplate;
+    private analyzeDynamicExpression;
+    private createValueGetter;
+    private createStaticFragment;
+}
+/**
+ * Render a compiled template efficiently
+ */
+export declare function renderCompiledTemplate<T>(compiled: CompiledTemplate<T>, state: T, api: any): DocumentFragment;
+/**
+ * Update a rendered template with new state efficiently
+ */
+export declare function updateCompiledTemplate<T>(compiled: CompiledTemplate<T>, element: Element, newState: T, api: any, oldState?: T): void;
+interface PerformanceMetrics {
+    compilationTime: number;
+    renderTime: number;
+    updateTime: number;
+    cacheHits: number;
+    cacheMisses: number;
+}
+/**
+ * Development helper to analyze template performance
+ */
+export declare function analyzeTemplate(template: string): {
+    staticParts: number;
+    dynamicParts: number;
+    complexity: 'low' | 'medium' | 'high';
+    recommendations: string[];
+};
+/**
+ * Clear template cache for development/testing
+ */
+export declare function clearTemplateCache(): void;
+/**
+ * Get performance metrics for development monitoring
+ */
+export declare function getPerformanceMetrics(): Map<string, PerformanceMetrics>;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(): {
+    size: number;
+    entries: string[];
+};
+export {};

package/dist/template-helpers.d.ts

@@ -0,0 +1,56 @@
+import type { CompiledTemplate } from './template-compiler.js';
+/**
+ * TemplateResult type for template helpers
+ */
+export type TemplateResult = string | CompiledTemplate | ((state?: any) => string);
+/**
+ * Tagged template literal for HTML strings.
+ * Returns a pure function for rendering with state and api.
+ * @param strings - Template strings
+ * @param values - Dynamic values (functions or primitives)
+ */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): (state?: any, api?: any) => string | Promise<string>;
+/**
+ * CompiledTemplateFn type for compiled templates
+ */
+export interface CompiledTemplateFn {
+    (state: any, api?: any): string;
+    id: string;
+}
+/**
+ * compile helper: returns a compiled template function with a unique id property.
+ * Accepts tagged template literals and dynamic values (functions or primitives).
+ * @param strings - Template strings
+ * @param values - Dynamic values
+ */
+export declare function compile(strings: TemplateStringsArray, ...values: any[]): CompiledTemplateFn;
+/**
+ * Tagged template literal for CSS strings.
+ * Returns a pure string for use in style blocks.
+ * @param strings - Template strings
+ * @param values - Dynamic values
+ */
+export declare function css(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * Create a ref function for element references.
+ * @param callback - Callback to run with the element
+ */
+export declare function ref<T extends Element = Element>(callback: (el: T) => void): (el: Element) => void;
+/**
+ * Create event handlers with strong typing for use in templates.
+ * @param eventType - Event type
+ * @param handler - Handler function
+ */
+export declare function on<K extends keyof HTMLElementEventMap>(eventType: K, handler: (event: HTMLElementEventMap[K], state: any, api: any) => void): {
+    [key in K]: (event: HTMLElementEventMap[K], state: any, api: any) => void;
+};
+/**
+ * Helper for conditional classes. Returns a space-separated string of class names.
+ * @param obj - Object with class names as keys and boolean conditions as values
+ */
+export declare function classes(obj: Record<string, boolean>): string;
+/**
+ * Helper for inline styles. Returns a CSS string for use in style attributes.
+ * @param obj - Object with style properties and values
+ */
+export declare function styles(obj: Record<string, string | number>): string;

package/dist/v-dom.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Utility: Generate a stable key for a VNode
+ */
+export declare function getVNodeKey(type: string, parentPath: string, childIndex: number, model?: string, value?: string): string;
+/**
+ * Virtual Node (VNode) structure for incremental migration
+ */
+export interface VNode {
+    type: string;
+    key?: string;
+    props: Record<string, any>;
+    children: VNode[];
+    dom?: Element | Text;
+}
+/**
+ * Safely replaces a child node, guarding against NotFoundError and out-of-sync trees.
+ * Falls back to appendChild if oldChild is not present.
+ * Logs mutation for debugging if enabled.
+ * @param parent - Parent node
+ * @param newChild - New node to insert
+ * @param oldChild - Old node to replace
+ */
+export declare function safeReplaceChild(parent: Node | null, newChild: Node, oldChild: Node): void;
+/**
+ * Mounts a VNode to the DOM and returns the created node.
+ * Handles text, fragment, and element nodes.
+ * @param vnode - Virtual node to mount
+ * @returns DOM node or null
+ */
+export declare function mountVNode(vnode: VNode): Element | Text | null;
+/**
+ * Parses an HTML string into a VNode tree.
+ * Supports basic tags, attributes, text, and key/data-model.
+ * @param html - HTML string
+ * @returns VNode tree
+ */
+export declare function parseVNodeFromHTML(html: string): VNode;
+/**
+ * Creates a VNode from a DOM ChildNode (Element or Text).
+ * Assigns a stable, deterministic key for VDOM reconciliation.
+ * @param node - DOM node
+ * @param parentPath - Path for key generation
+ * @param childIndex - Index for key generation
+ * @returns VNode
+ */
+export declare function createVNodeFromElement(node: ChildNode, parentPath?: string, childIndex?: number): VNode;
+/**
+ * Patches two VNodes and updates the DOM, preserving controlled inputs.
+ * Handles keyed and index-based reconciliation.
+ * @param parent - Parent DOM element
+ * @param oldVNode - Previous VNode
+ * @param newVNode - New VNode
+ */
+export declare function patchVNode(parent: Element, oldVNode: VNode, newVNode: VNode): void;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@jasonshimmy/custom-elements-runtime",
+  "description": "A powerful, modern, and lightweight runtime for creating reactive web components with TypeScript",
+  "version": "0.0.1-beta.0",
+  "type": "module",
+  "keywords": [
+    "web-components",
+    "custom-elements",
+    "reactive",
+    "typescript",
+    "frontend",
+    "ui"
+  ],
+  "author": "Jason Shimkoski <https://jasonshimmy.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jshimkoski/custom-elements.git"
+  },
+  "homepage": "https://github.com/jshimkoski/custom-elements#readme",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build && tsc",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "cy": "cypress run",
+    "cy:open": "cypress open"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "cypress": "^14.5.4",
+    "jsdom": "^26.1.0",
+    "typescript": "~5.8.3",
+    "vite": "^7.0.4",
+    "vitest": "^3.2.4"
+  },
+  "main": "dist/custom-elements-runtime.cjs.js",
+  "module": "dist/custom-elements-runtime.es.js",
+  "types": "dist/runtime.d.ts",
+  "files": [
+    "dist",
+    "dist/runtime.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/custom-elements-runtime.es.js",
+      "require": "./dist/custom-elements-runtime.cjs.js",
+      "default": "./dist/custom-elements-runtime.umd.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}