ezfw-core 1.0.0

package/core/renderer.ts

@@ -0,0 +1,1010 @@
+import { EzError } from './EzError.js';
+import { EzBaseComponent, EzBaseComponentConfig } from '../components/EzBaseComponent.js';
+import tooltipStyles from '../components/tooltip/EzTooltip.module.scss';
+import { cx } from '../utils/cssModules.js';
+
+const tooltipCls = cx(tooltipStyles);
+
+export type LazyMode = 'visible' | 'idle';
+
+export interface ComponentConfig extends EzBaseComponentConfig {
+    eztype?: string;
+    controller?: string;
+    ref?: string;
+    bind?: Record<string, unknown> | string;
+    cls?: string | string[];
+    flex?: number | string;
+    width?: number | string;
+    height?: number | string;
+    css?: string;
+    onLoad?: string | ((config: ComponentConfig, state: unknown) => Promise<void>);
+    fallback?: ComponentConfig | string | ((state: unknown) => Promise<ComponentConfig>);
+    skipFallback?: boolean;
+    skeleton?: boolean | ComponentConfig;
+    init?: string | ((config: ComponentConfig) => Promise<void>);
+    skipInit?: boolean;
+    name?: string;
+    items?: ComponentConfig[];
+    template?: (props: unknown, controller?: unknown, state?: unknown) => ComponentConfig;
+    props?: Record<string, unknown>;
+    _ezAfterRender?: (el: Node, instance: EzBaseComponent | null, config: ComponentConfig) => void;
+    _ezSourcePath?: string;
+    _onLoadComplete?: boolean;
+    _styleModule?: Record<string, string>;
+    lazy?: LazyMode;
+    lazyThreshold?: number;
+    lazyRootMargin?: string;
+    priority?: 'high' | 'low' | 'idle';
+    tooltip?: string | TooltipConfig;
+    store?: string | unknown;
+    routeParams?: Record<string, string>;
+    layout?: string;
+    style?: Record<string, string>;
+}
+
+interface TooltipConfig {
+    text: string;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    variant?: 'dark' | 'light';
+    delay?: number;
+}
+
+interface LazyQueueData {
+    config: ComponentConfig;
+    controllerName: string | null;
+    inheritedState: unknown;
+}
+
+interface ControllerInstance {
+    state?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+interface RegisteredComponent {
+    prototype?: { render?: () => HTMLElement | Promise<HTMLElement> };
+    controller?: string;
+    template?: (props: unknown, controller?: unknown, state?: unknown) => ComponentConfig;
+    onLoad?: string | ((config: ComponentConfig, state: unknown) => Promise<void>);
+    fallback?: ComponentConfig | string | ((state: unknown) => Promise<ComponentConfig>);
+    skipFallback?: boolean;
+    skeleton?: boolean | ComponentConfig;
+    css?: string;
+    cls?: string | string[];
+    layout?: string;
+    style?: Record<string, string>;
+    items?: ComponentConfig[];
+    [key: string]: unknown;
+}
+
+interface EzInstance {
+    _registry: Record<string, RegisteredComponent>;
+    _registryMeta?: Record<string, { definedIn?: string }>;
+    _controllers: Record<string, ControllerInstance>;
+    _refs: Record<string, EzBaseComponent>;
+    _context: {
+        route?: string | null;
+        view?: string | null;
+        controller?: string | null;
+    };
+    _loader: {
+        resolveController(name: string): Promise<unknown>;
+        resolveStore(name: string): Promise<void>;
+        resolveEzType(name: string): Promise<void>;
+        loadWithPriority(name: string, priority: string): Promise<void>;
+        getCurrentModulePath(): string | null;
+    };
+    getController(name: string): Promise<ControllerInstance>;
+    getStore(name: string): unknown;
+    registerComponent(name: string, component: unknown): void;
+    hasStyles(name: string): boolean;
+    resolveStyles(name: string): Promise<Record<string, string> | null>;
+    handleFrameworkError(error: Error): void;
+}
+
+export class EzRenderer {
+    private ez: EzInstance;
+    private _lazyQueue: Map<Element, LazyQueueData> = new Map();
+    private _lazyObserver: IntersectionObserver | null = null;
+
+    constructor(ez: EzInstance) {
+        this.ez = ez;
+        this._initLazyObserver();
+    }
+
+    private _initLazyObserver(): void {
+        if (typeof IntersectionObserver === 'undefined') return;
+
+        this._lazyObserver = new IntersectionObserver(
+            (entries) => {
+                for (const entry of entries) {
+                    if (!entry.isIntersecting) continue;
+
+                    const placeholder = entry.target;
+                    const data = this._lazyQueue.get(placeholder);
+
+                    if (!data) continue;
+
+                    this._lazyObserver!.unobserve(placeholder);
+                    this._lazyQueue.delete(placeholder);
+
+                    this._renderLazyComponent(placeholder as HTMLElement, data);
+                }
+            },
+            {
+                rootMargin: '50px',
+                threshold: 0.1
+            }
+        );
+    }
+
+    private async _renderLazyComponent(placeholder: HTMLElement, data: LazyQueueData): Promise<void> {
+        const { config, controllerName, inheritedState } = data;
+
+        try {
+            const renderConfig = { ...config, lazy: undefined };
+            const el = await this.createElement(renderConfig, controllerName, inheritedState);
+
+            if (placeholder.isConnected) {
+                placeholder.replaceWith(el);
+            }
+        } catch (err) {
+            this.ez.handleFrameworkError(err as Error);
+        }
+    }
+
+    private _createLazyPlaceholder(config: ComponentConfig, controllerName: string | null, inheritedState: unknown): HTMLElement {
+        const placeholder = document.createElement('div');
+        placeholder.className = 'ez-lazy-placeholder';
+        placeholder.setAttribute('data-lazy-eztype', config.eztype || 'EzComponent');
+
+        if (config.width) {
+            placeholder.style.width = typeof config.width === 'number'
+                ? `${config.width}px`
+                : config.width;
+        }
+        if (config.height) {
+            placeholder.style.height = typeof config.height === 'number'
+                ? `${config.height}px`
+                : config.height;
+        }
+        if (config.flex) {
+            placeholder.style.flex = config.flex.toString();
+        }
+
+        this._lazyQueue.set(placeholder, { config, controllerName, inheritedState });
+
+        if (config.lazyThreshold !== undefined || config.lazyRootMargin !== undefined) {
+            const customObserver = new IntersectionObserver(
+                (entries) => {
+                    for (const entry of entries) {
+                        if (!entry.isIntersecting) continue;
+
+                        customObserver.unobserve(entry.target);
+                        const data = this._lazyQueue.get(entry.target);
+                        if (data) {
+                            this._lazyQueue.delete(entry.target);
+                            this._renderLazyComponent(entry.target as HTMLElement, data);
+                        }
+                        customObserver.disconnect();
+                    }
+                },
+                {
+                    rootMargin: config.lazyRootMargin || '50px',
+                    threshold: config.lazyThreshold ?? 0.1
+                }
+            );
+            customObserver.observe(placeholder);
+        } else {
+            this._lazyObserver?.observe(placeholder);
+        }
+
+        return placeholder;
+    }
+
+    cloneConfig<T>(input: T, seen: WeakSet<object> = new WeakSet()): T {
+        if (input == null) return input;
+
+        const t = typeof input;
+        if (t !== 'object') return input;
+
+        if (input instanceof Node) return input;
+
+        if ((input as object).constructor !== Object && !Array.isArray(input)) {
+            return input;
+        }
+
+        if (seen.has(input as object)) {
+            return input;
+        }
+        seen.add(input as object);
+
+        if (input instanceof Set) return input;
+        if (input instanceof Map) return input;
+        if (input instanceof Date) return input;
+
+        if ((input as { _isEzStore?: boolean })._isEzStore) return input;
+
+        if (Array.isArray(input)) {
+            return input.map(v => this.cloneConfig(v, seen)) as T;
+        }
+
+        const out: Record<string, unknown> = {};
+        for (const k in input as Record<string, unknown>) {
+            out[k] = this.cloneConfig((input as Record<string, unknown>)[k], seen);
+        }
+        return out as T;
+    }
+
+    applyControllerBindings(config: ComponentConfig, controllerName: string): void {
+        if (!config || typeof config !== 'object') return;
+
+        const controller = this.ez._controllers[controllerName];
+
+        if (!controller) {
+            for (const key in config) {
+                if (key.startsWith('on') && typeof (config as Record<string, unknown>)[key] === 'string') {
+                    const src =
+                        config._ezSourcePath
+                        || this.ez._registryMeta?.[this.ez._context.view || '']?.definedIn
+                        || this.ez._loader?.getCurrentModulePath()
+                        || null;
+
+                    throw new EzError({
+                        code: 'EZ_HANDLER_NO_CONTROLLER',
+                        source: 'event',
+                        message: `Handler "${(config as Record<string, unknown>)[key]}" requires a controller but none is available`,
+                        route: this.ez._context.route,
+                        view: this.ez._context.view,
+                        details: {
+                            eztype: config.eztype,
+                            handler: key,
+                            method: (config as Record<string, unknown>)[key],
+                            route: src
+                        }
+                    });
+                }
+            }
+            return;
+        }
+
+        for (const key in config) {
+            const value = (config as Record<string, unknown>)[key];
+
+            if (typeof value === 'string' && typeof controller[value] === 'function') {
+                (config as Record<string, unknown>)[key] = (controller[value] as Function).bind(controller);
+            }
+        }
+
+        if (Array.isArray(config.items)) {
+            config.items.forEach(child => this.applyControllerBindings(child, controllerName));
+        }
+    }
+
+    async executeOnLoad(config: ComponentConfig, controllerName: string): Promise<void> {
+        if (!config.onLoad) return;
+
+        const controllerObj = await this.ez.getController(controllerName);
+
+        if (!controllerName || !controllerObj) {
+            throw new EzError({
+                code: 'EZ_ONLOAD_002',
+                source: 'component',
+                message: 'onLoad requires a valid controller',
+                route: this.ez._context.route,
+                view: this.ez._context.view,
+                details: {
+                    controller: controllerName
+                }
+            });
+        }
+
+        const controllerState = controllerObj.state;
+
+        let fn: unknown = config.onLoad;
+
+        if (typeof fn === 'string') {
+            const fnName = fn;
+            fn = controllerObj?.[fnName];
+            if (typeof fn !== 'function') {
+                const sourcePath =
+                    config._ezSourcePath
+                    || this.ez._registryMeta?.[this.ez._context.view || '']?.definedIn
+                    || this.ez._loader?.getCurrentModulePath()
+                    || null;
+
+                throw new EzError({
+                    code: 'EZ_ONLOAD_002',
+                    source: 'component',
+                    message: 'onLoad requires a valid controller',
+                    route: this.ez._context.route,
+                    view: this.ez._context.view,
+                    details: {
+                        controller: controllerName,
+                        file: sourcePath
+                    }
+                });
+            }
+        }
+
+        if (typeof fn === 'function') {
+            await fn.call(controllerObj, config, controllerState);
+        }
+    }
+
+    async executeOnInit(config: ComponentConfig, controllerName: string | null): Promise<void> {
+        let controller = this.ez._controllers[controllerName || ''];
+
+        if (!controller && config.controller) {
+            const ctrlName = typeof config.controller === 'string'
+                ? config.controller
+                : null;
+            if (ctrlName) {
+                controller = this.ez._controllers[ctrlName]
+                    || this.ez._controllers[`${ctrlName}Controller`];
+            } else if (typeof config.controller === 'object') {
+                controller = config.controller as ControllerInstance;
+            }
+        }
+
+        if (!controller) return;
+
+        let fn: unknown = config.init;
+        if (typeof fn === 'string') {
+            fn = controller[fn];
+        }
+
+        if (typeof fn === 'function') {
+            await fn.call(controller, config);
+        }
+    }
+
+    collectControllersFromBind(config: ComponentConfig): Set<string> {
+        const out: Set<string> = new Set();
+
+        const bind = config.bind;
+        if (!bind) return out;
+
+        const scan = (val: unknown): void => {
+            if (typeof val !== 'string') return;
+
+            const idx = val.indexOf(':');
+            if (idx > 0) {
+                out.add(val.slice(0, idx));
+            }
+        };
+
+        if (typeof bind === 'string') scan(bind);
+        else {
+            for (const key in bind) {
+                scan(bind[key]);
+            }
+        }
+
+        return out;
+    }
+
+    async createElement(config: ComponentConfig | ComponentConfig[] | null, controllerName: string | null = null, inheritedState: unknown = null): Promise<Node> {
+        if (!config) return document.createTextNode('');
+
+        if (Array.isArray(config)) {
+            const frag = document.createDocumentFragment();
+            for (const child of config) {
+                frag.appendChild(await this.createElement(child, controllerName, inheritedState));
+            }
+            return frag;
+        }
+
+        if (config.lazy === 'visible' && this._lazyObserver) {
+            return this._createLazyPlaceholder(config, controllerName, inheritedState);
+        }
+
+        const controllers: Set<string> = new Set();
+
+        if (config.controller) {
+            controllers.add(config.controller);
+        }
+
+        for (const c of this.collectControllersFromBind(config)) {
+            controllers.add(c);
+        }
+
+        for (const c of controllers) {
+            await this.ez._loader.resolveController(c);
+        }
+
+        if (typeof config.store === 'string') {
+            await this.ez._loader.resolveStore(config.store);
+            config = this.cloneConfig(config);
+            config.store = this.ez.getStore(config.store as string);
+        } else {
+            config = this.cloneConfig(config);
+        }
+
+        const { eztype = 'EzComponent', ref } = config;
+
+        let Registered = this.ez._registry[eztype] as RegisteredComponent | undefined;
+
+        const isFrameworkComponent = eztype.startsWith('Ez') || eztype[0] === eztype[0].toUpperCase();
+
+        if (!Registered && typeof eztype === 'string' && !isFrameworkComponent) {
+            const testEl = document.createElement(eztype);
+            if (testEl instanceof HTMLElement && !(eztype in this.ez._registry)) {
+                const { HtmlWrapper } = await import('../components/HtmlWrapper.js');
+
+                this.ez.registerComponent(eztype, HtmlWrapper);
+                Registered = HtmlWrapper as unknown as RegisteredComponent;
+            }
+        }
+
+        if (!Registered) {
+            const priority = config.priority || 'high';
+            await this.ez._loader.loadWithPriority(eztype, priority);
+            Registered = this.ez._registry[eztype] as RegisteredComponent | undefined;
+        }
+
+        if (!Registered) {
+            throw new EzError({
+                code: 'EZ_COMPONENT_500',
+                source: 'component',
+                message: `Invalid component type for eztype "${eztype}"`,
+                route: this.ez._context.route,
+                view: this.ez._context.view,
+                details: { eztype }
+            });
+        }
+
+        this.ez._context.controller = null;
+
+        const registeredController = typeof Registered === 'object' ? Registered.controller : null;
+        const activeController = config.controller || registeredController || controllerName || '';
+        await this.ez._loader.resolveController(activeController);
+
+        this.ez._context.controller = activeController;
+
+        if (activeController && !config.controller) {
+            config.controller = activeController;
+        }
+
+        const controllerState = this.ez._controllers[activeController]?.state;
+
+        this.applyControllerBindings(config, activeController);
+
+        const onLoadMethod = config._onLoadComplete ? null : (config.onLoad || (typeof Registered === 'object' ? Registered.onLoad : null));
+        let fallbackDef = config.fallback || (typeof Registered === 'object' ? Registered.fallback : null);
+        const skipFallback = config.skipFallback || (typeof Registered === 'object' ? Registered.skipFallback : false);
+        const skeletonMode = config.skeleton || (typeof Registered === 'object' ? Registered.skeleton : false);
+
+        if (skeletonMode && !fallbackDef && onLoadMethod) {
+            const skeletonCss = config.css || (typeof Registered === 'object' ? Registered.css : null);
+
+            if (skeletonCss) {
+                await this.ez.resolveStyles(skeletonCss);
+            }
+
+            const itemRenderFn = (config as { itemRender?: (data: unknown) => ComponentConfig }).itemRender || (typeof Registered === 'object' ? (Registered as { itemRender?: (data: unknown) => ComponentConfig }).itemRender : null);
+            if (itemRenderFn) {
+                try {
+                    const mockData = this._createMockData();
+                    const templateConfig = itemRenderFn(mockData);
+                    if (templateConfig) {
+                        fallbackDef = await this._buildSkeletonConfig(templateConfig, skeletonCss || undefined);
+                    }
+                } catch {
+                    // itemRender failed
+                }
+            }
+
+            if (!fallbackDef) {
+                const templateFn = config.template || (typeof Registered === 'object' ? Registered.template : null);
+                if (templateFn) {
+                    try {
+                        const templateConfig = templateFn({});
+                        if (templateConfig) {
+                            fallbackDef = await this._buildSkeletonConfig(templateConfig, skeletonCss || undefined);
+                        }
+                    } catch {
+                        // template failed
+                    }
+                }
+            }
+
+            if (!fallbackDef) {
+                const items = config.items || (typeof Registered === 'object' ? Registered.items : null);
+                if (items && Array.isArray(items)) {
+                    fallbackDef = await this._buildSkeletonConfig({
+                        eztype: 'EzComponent',
+                        cls: config.cls || (typeof Registered === 'object' ? Registered.cls : undefined),
+                        css: skeletonCss || undefined,
+                        layout: config.layout || (typeof Registered === 'object' ? Registered.layout : undefined),
+                        style: config.style || (typeof Registered === 'object' ? Registered.style : undefined),
+                        items: items
+                    }, skeletonCss || undefined);
+                }
+            }
+
+            if (!fallbackDef) {
+                fallbackDef = { eztype: 'EzSkeleton', variant: 'rect', css: skeletonCss || undefined } as unknown as ComponentConfig;
+            }
+        }
+
+        if (onLoadMethod) {
+            let fallbackConfig: ComponentConfig = {};
+
+            if (!fallbackDef && !skipFallback) {
+                throw new EzError({
+                    code: 'EZ_ONLOAD_001',
+                    source: 'component',
+                    message: 'onLoad requires a fallback component',
+                    route: this.ez._context.route,
+                    view: this.ez._context.view,
+                    details: {
+                        eztype,
+                        hint: 'Define a fallback property or use skeleton: true'
+                    }
+                });
+            }
+
+            if (fallbackDef && typeof fallbackDef === 'object') {
+                fallbackConfig = fallbackDef as ComponentConfig;
+            } else if (fallbackDef && typeof fallbackDef === 'function') {
+                fallbackConfig = await (fallbackDef as (state: unknown) => Promise<ComponentConfig>)(this.ez._controllers[activeController]?.state);
+            } else if (fallbackDef && typeof fallbackDef === 'string') {
+                let registered = this.ez._registry[fallbackDef];
+
+                if (!registered) {
+                    await this.ez._loader.resolveEzType(fallbackDef);
+                    registered = this.ez._registry[fallbackDef];
+                }
+
+                if (!registered) {
+                    throw new EzError({
+                        code: 'EZ_COMPONENT_500',
+                        source: 'component',
+                        message: `Invalid component type for eztype "${eztype}"`,
+                        route: this.ez._context.route,
+                        view: this.ez._context.view,
+                        details: { eztype }
+                    });
+                }
+
+                fallbackConfig = registered as unknown as ComponentConfig;
+            }
+
+            const fallbackEl = await this.createElement(fallbackConfig, activeController, inheritedState);
+
+            this.executeOnLoad({ ...config, onLoad: onLoadMethod }, activeController)
+                .then(async () => {
+                    if (!(fallbackEl as HTMLElement).isConnected) return;
+
+                    const rendered = await this.createElement({
+                        ...config,
+                        _onLoadComplete: true
+                    }, activeController, inheritedState);
+
+                    (fallbackEl as HTMLElement).replaceWith(rendered);
+                })
+                .catch(err => {
+                    this.ez.handleFrameworkError(err);
+                });
+
+            return fallbackEl;
+        }
+
+        let el: Node;
+        let instance: EzBaseComponent | null = null;
+
+        let styleModule: Record<string, string> | null = null;
+        if (config.css) {
+            styleModule = await this.ez.resolveStyles(config.css);
+            config._styleModule = styleModule || undefined;
+        }
+
+        if (Registered.prototype?.render) {
+            instance = new (Registered as unknown as new (config: ComponentConfig) => EzBaseComponent)(config);
+            const rendered = (instance as unknown as { render(): Node | Promise<Node> }).render();
+
+            if (rendered instanceof Promise) {
+                el = await rendered;
+            } else {
+                el = rendered;
+            }
+            (el as { __ezInstance?: EzBaseComponent }).__ezInstance = instance;
+            instance.el = el as HTMLElement;
+
+            if (typeof config._ezAfterRender === 'function') {
+                queueMicrotask(() => {
+                    try {
+                        config._ezAfterRender!(el, instance, config);
+                    } catch (err) {
+                        this.ez.handleFrameworkError(err as Error);
+                    }
+                });
+            }
+
+            if (config.name && el instanceof HTMLElement) {
+                el.setAttribute('data-ez-field', config.name);
+            }
+
+            if (inheritedState instanceof EzBaseComponent) {
+                (inheritedState as unknown as { _children?: EzBaseComponent[] })._children ??= [];
+                (inheritedState as unknown as { _children: EzBaseComponent[] })._children.push(instance);
+            }
+        } else if (typeof Registered === 'object') {
+            const { eztype: _, ...rest } = config;
+
+            let merged: ComponentConfig = { ...Registered as ComponentConfig, ...rest };
+
+            if (!merged.css && this.ez.hasStyles(eztype)) {
+                merged.css = eztype;
+            }
+
+            if (merged.css && !merged._styleModule) {
+                merged._styleModule = (await this.ez.resolveStyles(merged.css)) || undefined;
+            }
+
+            let targetIsClassComponent = false;
+            if (merged.eztype && merged.eztype !== 'EzComponent') {
+                const targetRegistered = this.ez._registry[merged.eztype];
+                if (targetRegistered?.prototype?.render) {
+                    targetIsClassComponent = true;
+                } else if (!targetRegistered) {
+                    try {
+                        await this.ez._loader.resolveEzType(merged.eztype);
+                        const resolved = this.ez._registry[merged.eztype];
+                        if (resolved?.prototype?.render) {
+                            targetIsClassComponent = true;
+                        }
+                    } catch {
+                        // Not found
+                    }
+                }
+            }
+
+            if (typeof merged.template === 'function' && !targetIsClassComponent) {
+                const inheritedCss = merged.css;
+                const inheritedStyleModule = merged._styleModule;
+
+                const tpl = merged.template(config.props || {}, this.ez._controllers[activeController], controllerState);
+                if (!tpl || typeof tpl !== 'object') {
+                    throw new EzError({
+                        code: 'EZ_TEMPLATE_001',
+                        source: 'component',
+                        message: 'template() must return a component config object',
+                        view: this.ez._context.view,
+                        route: this.ez._context.route
+                    });
+                }
+
+                merged = tpl;
+
+                if (inheritedCss && !merged.css) {
+                    merged.css = inheritedCss;
+                    merged._styleModule = inheritedStyleModule;
+                }
+            }
+
+            el = await this.createElement(merged, activeController, controllerState);
+        } else {
+            throw new EzError({
+                code: 'EZ_COMPONENT_500',
+                source: 'component',
+                message: `Invalid component type for eztype "${eztype}"`,
+                route: this.ez._context.route,
+                view: this.ez._context.view,
+                details: { eztype }
+            });
+        }
+
+        if (config.cls && el instanceof HTMLElement) {
+            if (Array.isArray(config.cls)) {
+                const resolvedClasses = config.cls.map(c => {
+                    if (styleModule && typeof c === 'string' && styleModule[c]) {
+                        return styleModule[c];
+                    }
+                    return c;
+                }).filter(Boolean);
+                if (resolvedClasses.length) {
+                    el.classList.add(...resolvedClasses);
+                }
+            } else if (typeof config.cls === 'string') {
+                const classes = config.cls.split(' ').filter(Boolean).map(c => {
+                    if (styleModule && styleModule[c]) {
+                        return styleModule[c];
+                    }
+                    return c;
+                });
+                if (classes.length) {
+                    el.classList.add(...classes);
+                }
+            }
+        }
+
+        if (config.tooltip && el instanceof HTMLElement) {
+            this._applyTooltip(el, config.tooltip, instance);
+        }
+
+        if (config.flex) {
+            (el as HTMLElement).style.flex = config.flex.toString();
+        }
+
+        if (ref && instance) {
+            this.ez._refs[ref] = instance;
+        }
+
+        if (!Registered.prototype?.render && config.items) {
+            const children = await this.createChildElements(
+                config.items,
+                activeController,
+                controllerState,
+                config.css || null
+            );
+            children.forEach(child => (el as HTMLElement).appendChild(child));
+        }
+
+        if (config.init && config.skipInit !== true) {
+            queueMicrotask(() => {
+                this.executeOnInit(config, controllerName)
+                    .catch(err => this.ez.handleFrameworkError(err));
+            });
+        }
+
+        return el;
+    }
+
+    async createChildElements(items: ComponentConfig[], controllerName: string, inheritedState: unknown, parentCss: string | null = null): Promise<Node[]> {
+        const out: Node[] = [];
+        if (!Array.isArray(items)) return out;
+
+        const parentSource = (inheritedState as { _ezSourcePath?: string })?._ezSourcePath || null;
+
+        for (const item of items) {
+            const localItem = item?.controller
+                ? this.cloneConfig(item)
+                : { ...this.cloneConfig(item), controller: controllerName };
+
+            if (!localItem._ezSourcePath) {
+                localItem._ezSourcePath = parentSource || undefined;
+            }
+
+            if (parentCss && !localItem.css) {
+                localItem.css = parentCss;
+            }
+
+            const child = await this.createElement(localItem, controllerName, inheritedState);
+
+            if (child instanceof Node) {
+                if (localItem.flex !== undefined) (child as HTMLElement).style.flex = localItem.flex.toString();
+                if (localItem.width !== undefined) (child as HTMLElement).style.width = typeof localItem.width === 'number' ? `${localItem.width}px` : localItem.width;
+                if (localItem.height !== undefined) (child as HTMLElement).style.height = typeof localItem.height === 'number' ? `${localItem.height}px` : localItem.height;
+                out.push(child);
+            }
+        }
+
+        return out;
+    }
+
+    _createMockData(): Record<string, unknown> {
+        return {
+            id: 1,
+            user_id: 1,
+            name: 'Loading...',
+            user_first_name: 'Loading',
+            user_last_name: '...',
+            user_full_name: 'Loading...',
+            title: 'Loading...',
+            email: 'loading@example.com',
+            phone: '000-000-0000',
+            avatar: '',
+            image: '',
+            description: 'Loading content...',
+            status: 'active',
+            created_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+            user_last_login: new Date().toISOString(),
+            role: { role_name: 'Loading...' }
+        };
+    }
+
+    async _buildSkeletonConfig(config: ComponentConfig, parentCss?: string): Promise<ComponentConfig> {
+        if (!config) return { eztype: 'EzSkeleton', variant: 'text' } as unknown as ComponentConfig;
+
+        const eztype = config.eztype || 'EzComponent';
+        const css = config.css || parentCss;
+
+        const contentElements: Record<string, string> = {
+            'h1': 'title', 'h2': 'title', 'h3': 'title',
+            'h4': 'text', 'h5': 'text', 'h6': 'text',
+            'p': 'text', 'span': 'text', 'label': 'text',
+            'img': 'rect',
+            'EzAvatar': 'circle',
+            'EzButton': 'rect',
+            'EzInput': 'rect',
+            'EzBadge': 'rect',
+            'StatCard': 'rect'
+        };
+
+        if (contentElements[eztype]) {
+            return {
+                eztype: 'EzSkeleton',
+                variant: contentElements[eztype],
+                cls: config.cls,
+                css: css,
+                style: config.style,
+                flex: config.flex,
+                rounded: eztype !== 'EzAvatar'
+            } as unknown as ComponentConfig;
+        }
+
+        if (eztype === 'EzComponent' || eztype === 'div' || eztype === 'section' || eztype === 'article') {
+            const result: ComponentConfig = {
+                eztype: eztype,
+                cls: config.cls,
+                css: css,
+                layout: config.layout,
+                flex: config.flex,
+                style: config.style
+            };
+
+            if (config.items && Array.isArray(config.items)) {
+                result.items = await Promise.all(config.items.map(item => this._buildSkeletonConfig(item, css)));
+            }
+
+            return result;
+        }
+
+        if (eztype[0] === eztype[0].toUpperCase()) {
+            await this.ez._loader.resolveEzType(eztype);
+            const registered = this.ez._registry[eztype];
+
+            const componentCss = (registered as { css?: string })?.css || parentCss;
+            if (componentCss) {
+                await this.ez.resolveStyles(componentCss);
+            }
+
+            if (registered && typeof registered === 'object') {
+                if ((registered as { skeleton?: ComponentConfig }).skeleton && typeof (registered as { skeleton?: ComponentConfig }).skeleton === 'object') {
+                    return await this._buildSkeletonConfig((registered as { skeleton: ComponentConfig }).skeleton, componentCss);
+                }
+
+                if (typeof (registered as { template?: (props: unknown) => ComponentConfig }).template === 'function') {
+                    try {
+                        const templateResult = (registered as { template: (props: unknown) => ComponentConfig }).template(config.props || {});
+                        if (templateResult) {
+                            return await this._buildSkeletonConfig(templateResult, componentCss);
+                        }
+                    } catch {
+                        // Template failed
+                    }
+                }
+
+                if ((registered as { items?: ComponentConfig[] }).items && Array.isArray((registered as { items?: ComponentConfig[] }).items)) {
+                    return {
+                        eztype: 'EzComponent',
+                        cls: (registered as { cls?: string | string[] }).cls,
+                        css: componentCss,
+                        layout: (registered as { layout?: string }).layout,
+                        style: (registered as { style?: Record<string, string> }).style,
+                        flex: config.flex,
+                        items: await Promise.all((registered as { items: ComponentConfig[] }).items.map(item => this._buildSkeletonConfig(item, componentCss)))
+                    };
+                }
+            }
+
+            return {
+                eztype: 'EzSkeleton',
+                variant: 'rect',
+                cls: config.cls,
+                css: css,
+                flex: config.flex,
+                rounded: true
+            } as unknown as ComponentConfig;
+        }
+
+        return {
+            eztype: 'EzSkeleton',
+            variant: 'rect',
+            cls: config.cls,
+            css: css,
+            flex: config.flex
+        } as unknown as ComponentConfig;
+    }
+
+    _applyTooltip(el: HTMLElement, tipConfig: string | TooltipConfig, instance: EzBaseComponent | null): void {
+        const text = typeof tipConfig === 'string' ? tipConfig : tipConfig.text;
+        const position = (typeof tipConfig === 'object' ? tipConfig.position : null) || 'top';
+        const variant = (typeof tipConfig === 'object' ? tipConfig.variant : null) || 'dark';
+        const delay = (typeof tipConfig === 'object' ? tipConfig.delay : null) ?? 200;
+
+        if (!text) return;
+
+        const tooltip = document.createElement('div');
+        tooltip.className = tooltipCls('tooltip', variant);
+        tooltip.textContent = text;
+        tooltip.style.opacity = '0';
+        tooltip.style.visibility = 'hidden';
+
+        const arrow = document.createElement('div');
+        arrow.className = tooltipCls('arrow');
+        tooltip.appendChild(arrow);
+
+        document.body.appendChild(tooltip);
+
+        let showTimeout: ReturnType<typeof setTimeout> | null = null;
+        let hideTimeout: ReturnType<typeof setTimeout> | null = null;
+
+        const showTooltip = (): void => {
+            if (hideTimeout) clearTimeout(hideTimeout);
+            showTimeout = setTimeout(() => {
+                const rect = el.getBoundingClientRect();
+                const tooltipRect = tooltip.getBoundingClientRect();
+
+                let top: number, left: number;
+
+                switch (position) {
+                    case 'top':
+                        top = rect.top - tooltipRect.height - 8;
+                        left = rect.left + (rect.width - tooltipRect.width) / 2;
+                        break;
+                    case 'bottom':
+                        top = rect.bottom + 8;
+                        left = rect.left + (rect.width - tooltipRect.width) / 2;
+                        break;
+                    case 'left':
+                        top = rect.top + (rect.height - tooltipRect.height) / 2;
+                        left = rect.left - tooltipRect.width - 8;
+                        break;
+                    case 'right':
+                        top = rect.top + (rect.height - tooltipRect.height) / 2;
+                        left = rect.right + 8;
+                        break;
+                    default:
+                        top = rect.top - tooltipRect.height - 8;
+                        left = rect.left + (rect.width - tooltipRect.width) / 2;
+                }
+
+                const padding = 8;
+                if (left < padding) left = padding;
+                if (left + tooltipRect.width > window.innerWidth - padding) {
+                    left = window.innerWidth - tooltipRect.width - padding;
+                }
+                if (top < padding) top = padding;
+                if (top + tooltipRect.height > window.innerHeight - padding) {
+                    top = window.innerHeight - tooltipRect.height - padding;
+                }
+
+                tooltip.style.top = `${top + window.scrollY}px`;
+                tooltip.style.left = `${left + window.scrollX}px`;
+                tooltip.className = tooltipCls('tooltip', variant, position);
+                tooltip.style.opacity = '1';
+                tooltip.style.visibility = 'visible';
+            }, delay);
+        };
+
+        const hideTooltip = (): void => {
+            if (showTimeout) clearTimeout(showTimeout);
+            hideTimeout = setTimeout(() => {
+                tooltip.style.opacity = '0';
+                tooltip.style.visibility = 'hidden';
+            }, 0);
+        };
+
+        el.addEventListener('mouseenter', showTooltip);
+        el.addEventListener('mouseleave', hideTooltip);
+        el.addEventListener('focus', showTooltip);
+        el.addEventListener('blur', hideTooltip);
+
+        if (instance) {
+            const originalDestroy = instance.destroy?.bind(instance);
+            instance.destroy = (): void => {
+                if (showTimeout) clearTimeout(showTimeout);
+                if (hideTimeout) clearTimeout(hideTimeout);
+                el.removeEventListener('mouseenter', showTooltip);
+                el.removeEventListener('mouseleave', hideTooltip);
+                el.removeEventListener('focus', showTooltip);
+                el.removeEventListener('blur', hideTooltip);
+                if (tooltip.parentNode) tooltip.parentNode.removeChild(tooltip);
+                if (originalDestroy) originalDestroy();
+            };
+        }
+    }
+}