@jasonshimmy/custom-elements-runtime 0.0.10 → 0.0.12

package/dist/directives.d.ts

@@ -0,0 +1,11 @@
+import type { VNode } from "./vdom";
+export declare function when(cond: boolean, children: VNode | VNode[]): VNode;
+export declare function each<T extends string | number | boolean | {
+    id?: string | number;
+    key?: string;
+}>(list: T[], render: (item: T, index: number) => VNode | VNode[]): VNode[];
+export declare function match(): {
+    when(cond: any, content: VNode | VNode[]): /*elided*/ any;
+    otherwise(content: VNode | VNode[]): /*elided*/ any;
+    done(): VNode[];
+};

package/dist/router.d.ts

@@ -3,6 +3,7 @@
  * - Functional API, zero dependencies, SSR/static site compatible
  * - Integrates with Store and runtime.ts
  */
+import { type Store } from './store';
 export interface Route {
     path: string;
     component?: string;
@@ -26,22 +27,32 @@ export interface RouteState {
  */
 export declare function resolveRouteComponent(route: Route): Promise<any>;
 export declare function useRouter(config: RouterConfig): {
-    store: {
-        subscribe: (listener: (state: object) => void) => void;
-        getState: () => object;
-    };
+    store: Store<RouteState>;
     push: (path: string) => void;
     replace: (path: string) => void;
     back: () => void;
-    subscribe: (listener: (state: object) => void) => void;
+    subscribe: (listener: (state: RouteState) => void) => void;
     matchRoute: (path: string) => {
         route: Route | null;
         params: Record<string, string>;
     };
-    getCurrent: () => object;
+    getCurrent: () => RouteState;
     resolveRouteComponent: typeof resolveRouteComponent;
 };
 export declare function matchRouteSSR(routes: Route[], path: string): {
     route: Route | null;
     params: Record<string, string>;
 };
+export declare function initRouter(config: RouterConfig): {
+    store: Store<RouteState>;
+    push: (path: string) => void;
+    replace: (path: string) => void;
+    back: () => void;
+    subscribe: (listener: (state: RouteState) => void) => void;
+    matchRoute: (path: string) => {
+        route: Route | null;
+        params: Record<string, string>;
+    };
+    getCurrent: () => RouteState;
+    resolveRouteComponent: typeof resolveRouteComponent;
+};

package/dist/runtime.d.ts

@@ -1,144 +1,61 @@
 /**
- * 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;
-    render(): 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;
+ * runtime.ts
+ * 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 data-on-* attributes.
+ * No external dependencies. Mobile-first, secure, and developer friendly.
+ */
+export { createStore } from "./store";
+export { eventBus } from "./event-bus";
+export { html } from "./template-compiler";
+export { when, each, match } from "./directives";
+import { type VNode } from "./vdom";
+type LifecycleKeys = "onConnected" | "onDisconnected" | "onAttributeChanged" | "onError" | "errorFallback";
+interface WatchOptions {
+    immediate?: boolean;
+    deep?: boolean;
 }
-/**
- * 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;
-/**
- * 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;
+type WatchCallback<T = any, S = any> = (newValue: T, oldValue: T, context?: S) => void;
+type WatchConfig<S> = {
+    [K in keyof S]?: WatchCallback<S[K]> | [WatchCallback<S[K]>, WatchOptions?];
+} | Record<string, WatchCallback | [WatchCallback, WatchOptions?]>;
+type InferMethods<T> = {
+    [K in keyof T as K extends LifecycleKeys ? never : K]: T[K] extends Function ? T[K] : never;
 };
-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 } 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';
-export { useRouter, matchRouteSSR, resolveRouteComponent } from './router';
-export type { Route, RouterConfig, RouteState } from './router';
-import type { CompiledTemplate } from './template-compiler';
-import type { RouterConfig } from './router';
-/**
- * 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;
-/**
- * RouterLink component state
- */
-export interface RouterLinkState extends ComponentState {
-    to: string;
-    tag: string;
-    replace: boolean;
-    exact: boolean;
-    activeClass: string;
-    exactActiveClass: string;
-    ariaCurrentValue: string;
-    disabled: boolean;
-    external: boolean;
-    style: string;
+export type ComponentContext<S extends object, C extends object, P extends object, T extends object = any> = S & C & P & InferMethods<T>;
+export interface ComponentConfig<S extends object, C extends object = {}, P extends object = {}, T extends object = any> {
+    state?: S;
+    computed?: {
+        [K in keyof C]: (context: ComponentContext<S, C, P, T>) => C[K];
+    };
+    props?: Record<string, {
+        type: StringConstructor | NumberConstructor | BooleanConstructor;
+        default?: string | number | boolean;
+    }>;
+    watch?: WatchConfig<ComponentContext<S, C, P, T>>;
+    style?: string | ((context: ComponentContext<S, C, P, T>) => string);
+    minifyCSS?: boolean;
+    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;
+    [key: string]: any;
 }
 /**
- * Singleton router instance for global access.
+ * CSS template literal
  *
- * Define here to prevent circular dependency
- * issue with component.
- */
-export declare function initRouter(config: RouterConfig): {
-    store: {
-        subscribe: (listener: (state: object) => void) => void;
-        getState: () => object;
-    };
-    push: (path: string) => void;
-    replace: (path: string) => void;
-    back: () => void;
-    subscribe: (listener: (state: object) => void) => void;
-    matchRoute: (path: string) => {
-        route: import("./router").Route | null;
-        params: Record<string, string>;
-    };
-    getCurrent: () => object;
-    resolveRouteComponent: typeof import("./router").resolveRouteComponent;
+ * This doesn't sanitize CSS values.
+ * Runtime does that for us.
+ *
+ * @param strings
+ * @param values
+ * @returns
+ */
+export declare function css(strings: TemplateStringsArray, ...values: unknown[]): string;
+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>(config: ComponentConfig<S, C, P, T>): CustomElementConstructor | {
+    new (): object;
 };

package/dist/store.d.ts

@@ -1,5 +1,9 @@
 type Listener<T> = (state: T) => void;
-export declare function Store<T extends object>(initial: T): {
+export interface Store<T extends object> {
+    subscribe(listener: Listener<T>): void;
+    getState(): T;
+}
+export declare function createStore<T extends object>(initial: T): {
     subscribe: (listener: Listener<T>) => void;
     getState: () => T;
 };

package/dist/style-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CSS minification utility (basic)
+ */
+export declare function minifyCSS(css: string): string;
+/**
+ * Minimal Shadow DOM reset
+ */
+export declare const baseReset = "\n  :host {\n    box-sizing:border-box;\n    line-height:1.5;\n    font-family:ui-sans-serif,system-ui,sans-serif;\n    -webkit-text-size-adjust:100%;\n    text-size-adjust:100%;\n  }\n  *,::before,::after {\n    box-sizing:inherit;\n    margin:0;\n    padding:0;\n    border:0 solid currentColor;\n  }\n";
+export declare function jitCSS(html: string): string;

package/dist/template-compiler.d.ts

@@ -1,117 +1,6 @@
+import type { VNode } from "./vdom";
+export declare function h(tag: string, props?: Record<string, any>, children?: VNode[] | string, key?: string | number): VNode;
 /**
- * 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
+ * Default export: plain html.
  */
-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 {};
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): VNode | VNode[];

package/dist/vdom.d.ts

@@ -0,0 +1,32 @@
+/**
+ * vdom.ts
+ * Lightweight, strongly typed, functional virtual DOM renderer for custom elements.
+ * Features: keyed diffing, incremental patching, focus/caret preservation, event delegation, SSR-friendly, no dependencies.
+ */
+export interface VNode {
+    tag: string;
+    key?: string;
+    props?: {
+        key?: string;
+        props?: any;
+        attrs?: Record<string, any>;
+        directives?: Record<string, {
+            value: string;
+            modifiers: string[];
+        }>;
+    };
+    children?: VNode[] | string;
+}
+export interface AnchorBlockVNode extends VNode {
+    tag: "#anchor";
+    key: string;
+    children: VNode[];
+    _startNode?: Comment;
+    _endNode?: Comment;
+}
+/**
+ * Main renderer: uses patching and keys for node reuse.
+ * Never uses innerHTML. Only updates what has changed.
+ */
+export declare function vdomRenderer(root: ShadowRoot, vnodeOrArray: VNode | VNode[], context?: any): void;
+export declare function renderToString(vnode: VNode): string;

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.0.10",
+  "version": "0.0.12",
   "type": "module",
   "keywords": [
     "web-components",
@@ -29,12 +29,12 @@
     "cy:open": "cypress open"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.6.4",
+    "@testing-library/jest-dom": "^6.8.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "cypress": "^14.5.4",
+    "cypress": "^15.0.0",
     "jsdom": "^26.1.0",
-    "typescript": "~5.8.3",
-    "vite": "^7.0.4",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3",
     "vitest": "^3.2.4"
   },
   "main": "dist/custom-elements-runtime.cjs.js",

package/dist/build-tools.d.ts

@@ -1,66 +0,0 @@
-/**
- * Build Tool Integration for Template Compilation
- *
- * This file demonstrates how template compilation would integrate with build tools
- * like Vite, Webpack, or Rollup for optimal production performance.
- */
-import { type CompiledTemplate, type TemplateCompilerOptions } from '../lib/template-compiler.js';
-/**
- * Vite Plugin for Template Compilation
- * This would be a real Vite plugin in production
- */
-export declare function createTemplateCompilerPlugin(options?: TemplateCompilerOptions): {
-    name: string;
-    transform(code: string, id: string): {
-        code: string;
-        map: null;
-    } | null;
-};
-/**
- * Development-time template analyzer
- */
-export declare class TemplateDevTools {
-    private static readonly templates;
-    static analyzeTemplate(templateString: string): void;
-    static getStats(): {
-        totalTemplates: number;
-        totalUsage: number;
-        complexityDistribution: {
-            low: number;
-            medium: number;
-            high: number;
-        };
-        recommendations: string[];
-    };
-    static clear(): void;
-}
-/**
- * Performance monitor for template rendering
- */
-export declare class TemplatePerformanceMonitor {
-    private static readonly metrics;
-    static startRender(templateId: string): () => void;
-    private static recordRender;
-    static getMetrics(): {
-        templates: number;
-        totalRenders: number;
-        averageRenderTime: number;
-        slowestTemplate: {
-            id: string;
-            time: number;
-        } | null;
-        fastestTemplate: {
-            id: string;
-            time: number;
-        } | null;
-    };
-    static clear(): void;
-}
-/**
- * Helper to migrate from string templates to compiled templates
- */
-export declare function migrateToCompiledTemplate(stringTemplate: string, options?: TemplateCompilerOptions): {
-    compiled: CompiledTemplate;
-    migrationNotes: string[];
-    estimatedPerformanceGain: string;
-};

package/dist/computed-state.d.ts

@@ -1,10 +0,0 @@
-/**
- * Lightweight reactive state with computed properties and change notification.
- * @template T - State shape
- * @template C - Computed property map
- */
-export declare function reactive<T extends object, C extends Record<string, (state: T) => any>>(initialState: T, computedMap?: C): T & {
-    subscribe: (fn: (state: T) => void) => () => void;
-} & {
-    [K in keyof C]: ReturnType<C[K]>;
-};

package/dist/data-binding.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-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/ssr.d.ts

@@ -1,49 +0,0 @@
-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;