ezfw-core 1.0.28 → 1.0.29

package/components/EzBaseComponent.ts

@@ -11,11 +11,15 @@ const tooltipCls = cx(tooltipStyles);
 
 declare const ez: {
     _controllers: Record<string, EzController | undefined>;
-    getController(name: string): EzController | null;
+    getController(name: string): Promise<EzController | null>;
     getControllerSync(name: string): EzController | null;
     getDeepValue(obj: unknown, path: string[]): unknown;
     setDeepValue(obj: unknown, path: string[], value: unknown): void;
-    _createElement(config: EzComponentConfig): Promise<HTMLElement>;
+    _createElement(
+        config: EzComponentConfig,
+        controllerName?: string | null,
+        inheritedState?: unknown
+    ): Promise<HTMLElement>;
     hasStyles(name: string): boolean;
 };
 
@@ -33,7 +37,8 @@ type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
 type TooltipVariant = 'dark' | 'light';
 
 interface TooltipConfig {
-    text: string;
+    text?: string;
+    component?: EzComponentConfig;
     position?: TooltipPosition;
     variant?: TooltipVariant;
     delay?: number;
@@ -45,8 +50,16 @@ interface BindConfig {
     visible?: string;
     cls?: string | (() => string);
     html?: string | (() => string);
+    sanitizeHtml?: boolean;
     style?: Record<string, string> | (() => Record<string, string>);
     text?: string | (() => string);
+    [key: string]: unknown;
+}
+
+function sanitizeHtml(html: string): string {
+    const div = document.createElement('div');
+    div.textContent = html;
+    return div.innerHTML;
 }
 
 type StyleValue = string | number | undefined;
@@ -130,6 +143,9 @@ export interface EzComponentConfig {
     // Wrapper for grouping shortcuts
     ezStyle?: EzStyleShortcuts;
 
+    // Behavior shortcuts
+    showOnHover?: boolean;
+
     [key: string]: unknown;
 }
 
@@ -158,18 +174,45 @@ export class EzBaseComponent {
     config: EzComponentConfig;
     props: Record<string, unknown>;
     el: HTMLElement | null = null;
+    controller: EzController | null = null;
 
     protected _effects?: EffectCleanup[];
     protected _domListeners?: DomListenerCleanup[];
     protected _children?: EzBaseComponent[];
     protected _tooltip?: HTMLDivElement;
     protected _tooltipCleanup?: () => void;
+    protected _activateHandler?: (e: Event) => void;
+    protected _showOnHoverCleanup?: () => void;
 
     constructor(config: EzComponentConfig = {}) {
         this.config = config;
         this.props = config.props || {};
     }
 
+    /**
+     * Lifecycle method called when component becomes active/visible.
+     * Override in subclasses to handle activation (e.g., reload data).
+     * Triggered by parent containers like EzTabPanel via 'ez-activate' event.
+     */
+    onActivate(): void {
+        // Override in subclasses
+    }
+
+    /**
+     * Setup activation listener on element.
+     * Call this in render() after element is created.
+     */
+    protected _setupActivateListener(el: HTMLElement): void {
+        this._activateHandler = () => this.onActivate();
+        el.addEventListener('ez-activate', this._activateHandler);
+    }
+
+    protected async _resolveController(): Promise<void> {
+        if (this.config.controller) {
+            this.controller = await ez.getController(this.config.controller);
+        }
+    }
+
     /**
      * Resolve binding configuration to get controller and path.
      * Supports:
@@ -195,7 +238,7 @@ export class EzBaseComponent {
 
         if (!controllerName) return null;
 
-        const controller = ez.getController(controllerName);
+        const controller = ez.getControllerSync(controllerName);
         if (!controller?.state) return null;
 
         return {
@@ -214,7 +257,7 @@ export class EzBaseComponent {
         }
 
         if (typeof this.config.onChange === 'string') {
-            const controller = ez.getController(this.config.controller ?? '');
+            const controller = ez.getControllerSync(this.config.controller ?? '');
             const method = controller?.[this.config.onChange];
             if (typeof method === 'function') {
                 return (method as (value: unknown) => void).bind(controller);
@@ -249,6 +292,7 @@ export class EzBaseComponent {
             el.tagName === 'INPUT' ||
             el.tagName === 'TEXTAREA' ||
             el.tagName === 'SELECT';
+        const isCheckbox = el.tagName === 'INPUT' && (el as HTMLInputElement).type === 'checkbox';
 
         // 2️⃣ String bind: 'AppController:prop'
         if (typeof bind === 'string') {
@@ -273,12 +317,18 @@ export class EzBaseComponent {
                         ? ez._controllers[ctrl!]?.state[props[0]]
                         : ez.getDeepValue(ez._controllers[ctrl!]?.state, props!);
 
-                const nextStr = (next as string) ?? '';
-                if (isInput) {
+                if (isCheckbox) {
+                    const nextBool = !!next;
+                    if ((el as HTMLInputElement).checked !== nextBool) {
+                        (el as HTMLInputElement).checked = nextBool;
+                    }
+                } else if (isInput) {
+                    const nextStr = (next as string) ?? '';
                     if ((el as HTMLInputElement).value !== nextStr) {
                         (el as HTMLInputElement).value = nextStr;
                     }
                 } else {
+                    const nextStr = (next as string) ?? '';
                     if (el.textContent !== nextStr) {
                         el.textContent = nextStr;
                     }
@@ -289,13 +339,13 @@ export class EzBaseComponent {
 
         // 3️⃣ Object bind
         if (typeof bind === 'object') {
-            this._applyValueBind(el, bind, ctrl, isInput);
+            this._applyValueBind(el, bind, ctrl, isInput, isCheckbox);
             this._applyDataBind(el, bind, ctrl);
-            this._applyVisibleBind(el, bind);
-            this._applyClsBind(el, bind);
-            this._applyStyleBind(el, bind);
-            this._applyTextBind(el, bind);
-            this._applyHtmlBind(el, bind);
+            this._applyVisibleBind(el, bind, ctrl);
+            this._applyClsBind(el, bind, ctrl);
+            this._applyStyleBind(el, bind, ctrl);
+            this._applyTextBind(el, bind, ctrl);
+            this._applyHtmlBind(el, bind, ctrl);
         }
     }
 
@@ -303,7 +353,8 @@ export class EzBaseComponent {
         el: HTMLElement,
         bind: BindConfig,
         ctrl: string | undefined,
-        isInput: boolean
+        isInput: boolean,
+        isCheckbox: boolean
     ): void {
         if (!bind.value) return;
 
@@ -330,12 +381,18 @@ export class EzBaseComponent {
                     ? ez._controllers[activeCtrl!]?.state[props[0]]
                     : ez.getDeepValue(ez._controllers[activeCtrl!]?.state, props!);
 
-            const nextStr = (next as string) ?? '';
-            if (isInput) {
+            if (isCheckbox) {
+                const nextBool = !!next;
+                if ((el as HTMLInputElement).checked !== nextBool) {
+                    (el as HTMLInputElement).checked = nextBool;
+                }
+            } else if (isInput) {
+                const nextStr = (next as string) ?? '';
                 if ((el as HTMLInputElement).value !== nextStr) {
                     (el as HTMLInputElement).value = nextStr;
                 }
             } else {
+                const nextStr = (next as string) ?? '';
                 if (el.textContent !== nextStr) {
                     el.textContent = nextStr;
                 }
@@ -391,6 +448,21 @@ export class EzBaseComponent {
                 // Check if this render is still current before modifying DOM
                 if (renderVersion !== currentRenderVersion) return;
 
+                // Destroy old children before clearing (they have tooltips, etc.)
+                if (this._children) {
+                    const childrenToRemove: EzBaseComponent[] = [];
+                    for (const child of this._children) {
+                        if (child.el && el.contains(child.el)) {
+                            childrenToRemove.push(child);
+                        }
+                    }
+                    for (const child of childrenToRemove) {
+                        child.destroy();
+                        const idx = this._children.indexOf(child);
+                        if (idx !== -1) this._children.splice(idx, 1);
+                    }
+                }
+
                 el.innerHTML = '';
 
                 if (Array.isArray(data)) {
@@ -427,7 +499,8 @@ export class EzBaseComponent {
                             childCfg.css = this.config.css;
                             childCfg._styleModule = this.config._styleModule;
                         }
-                        const childEl = await ez._createElement(childCfg);
+                        // Pass 'this' as inheritedState so children are added to _children
+                        const childEl = await ez._createElement(childCfg, null, this);
 
                         // Final check before appending
                         if (renderVersion !== currentRenderVersion) return;
@@ -440,7 +513,7 @@ export class EzBaseComponent {
         this._effects!.push(stop);
     }
 
-    private _applyVisibleBind(el: HTMLElement, bind: BindConfig): void {
+    private _applyVisibleBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
         if (!bind.visible) return;
 
         const expr = bind.visible;
@@ -453,20 +526,30 @@ export class EzBaseComponent {
             rightExpr: string;
         }
 
-        function parseVisibilityExpression(expr: string): ParsedVisibility | null {
+        function parseVisibilityExpression(expr: string, defaultCtrl: string | undefined): ParsedVisibility | null {
             const operatorMatch = expr.match(/(>=|<=|==|!=|>|<)/);
             if (!operatorMatch) return null;
 
             const operator = operatorMatch[0];
             const [leftExpr, rightExpr] = expr.split(operator).map(s => s.trim());
 
-            const [controllerName, propertyPath] = leftExpr.split(':');
-            const props = propertyPath.split('.');
+            let controllerName: string;
+            let propertyPath: string;
+
+            if (leftExpr.includes(':')) {
+                [controllerName, propertyPath] = leftExpr.split(':');
+            } else {
+                controllerName = defaultCtrl || '';
+                propertyPath = leftExpr;
+            }
+
+            if (!controllerName) return null;
 
+            const props = propertyPath.split('.');
             return { controllerName, props, operator, rightExpr };
         }
 
-        const parsed = parseVisibilityExpression(expr);
+        const parsed = parseVisibilityExpression(expr, ctrl);
 
         if (parsed) {
             const { controllerName, props, operator, rightExpr } = parsed;
@@ -488,48 +571,97 @@ export class EzBaseComponent {
                 }
 
                 if (result) {
-                    el.style.removeProperty('display');
+                    el.removeAttribute('data-ez-hidden');
                 } else {
-                    el.style.setProperty('display', 'none', 'important');
+                    el.setAttribute('data-ez-hidden', '');
                 }
             });
             this._effects!.push(stop);
-        } else if (expr.includes(':')) {
-            const [controllerName, path] = expr.split(':');
-            const props = path?.split('.');
-
-            if (!controllerName || !props) {
-                console.warn(`[ez] Invalid visible expression format: ${expr}`);
-                return;
+        } else {
+            // Simple boolean binding: 'Controller:path' or 'path'
+            let activeCtrl = ctrl;
+            let props: string[];
+
+            if (expr.includes(':')) {
+                const [controllerName, path] = expr.split(':');
+                if (!controllerName || !path) {
+                    console.warn(`[ez] Invalid visible expression format: ${expr}`);
+                    return;
+                }
+                activeCtrl = controllerName;
+                props = path.split('.');
+            } else {
+                if (!activeCtrl) {
+                    console.warn(`[ez] No controller specified for visible binding: ${expr}`);
+                    return;
+                }
+                props = expr.split('.');
             }
 
             const stop = effect(() => {
-                const result = !!ez.getDeepValue(ez._controllers[controllerName]?.state, props);
-                el.style.display = result ? '' : 'none';
+                const result = !!ez.getDeepValue(ez._controllers[activeCtrl!]?.state, props);
+                if (result) {
+                    el.removeAttribute('data-ez-hidden');
+                } else {
+                    el.setAttribute('data-ez-hidden', '');
+                }
             });
             this._effects!.push(stop);
-
-        } else {
-            console.warn(`[ez] Unsupported visibility expression: ${expr}`);
         }
     }
 
-    private _applyClsBind(el: HTMLElement, bind: BindConfig): void {
+    private _applyClsBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
         if (!bind.cls) return;
 
         let prevClasses: string[] = [];
         const styleModule = this.config._styleModule;
 
-        const stop = effect(() => {
-            let next = bind.cls;
+        // If cls is a function, call it reactively
+        if (typeof bind.cls === 'function') {
+            const stop = effect(() => {
+                const next = (bind.cls as () => string)() || '';
+                const classes = next.split(' ').filter(Boolean).map(c => {
+                    if (styleModule && styleModule[c]) {
+                        return styleModule[c];
+                    }
+                    return c;
+                });
 
-            if (typeof next === 'function') {
-                next = next();
-            }
+                if (prevClasses.length) {
+                    el.classList.remove(...prevClasses);
+                }
+                if (classes.length) {
+                    el.classList.add(...classes);
+                }
+                prevClasses = classes;
+            });
+            this._effects!.push(stop);
+            return;
+        }
+
+        // If cls is a string, treat it as a state path
+        const clsPath = bind.cls;
+        let props: string[];
+        let activeCtrl = ctrl;
 
-            if (typeof next !== 'string') {
-                next = '';
+        if (clsPath.includes(':')) {
+            const [controller, path] = clsPath.split(':');
+            if (!controller) {
+                console.warn(`[ez] Invalid bind.cls format: ${clsPath}`);
+                return;
             }
+            activeCtrl = controller;
+            props = path.split('.');
+        } else {
+            props = clsPath.split('.');
+        }
+
+        const stop = effect(() => {
+            const next = (
+                props.length === 1
+                    ? ez._controllers[activeCtrl!]?.state[props[0]]
+                    : ez.getDeepValue(ez._controllers[activeCtrl!]?.state, props)
+            ) as string || '';
 
             const classes = next.split(' ').filter(Boolean).map(c => {
                 if (styleModule && styleModule[c]) {
@@ -541,88 +673,164 @@ export class EzBaseComponent {
             if (prevClasses.length) {
                 el.classList.remove(...prevClasses);
             }
-
             if (classes.length) {
                 el.classList.add(...classes);
             }
-
             prevClasses = classes;
         });
 
         this._effects!.push(stop);
     }
 
-    private _applyHtmlBind(el: HTMLElement, bind: BindConfig): void {
+    private _applyHtmlBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
         if (!bind.html) return;
 
-        const stop = effect(() => {
-            let next = bind.html;
+        const shouldSanitize = bind.sanitizeHtml === true;
 
-            if (typeof next === 'function') {
-                next = next();
-            }
+        // If html is a function, call it reactively
+        if (typeof bind.html === 'function') {
+            const stop = effect(() => {
+                const next = (bind.html as () => string)();
+                const content = String(next ?? '');
+                el.innerHTML = shouldSanitize ? sanitizeHtml(content) : content;
+            });
+            this._effects!.push(stop);
+            return;
+        }
+
+        // If html is a string, treat it as a state path
+        const htmlPath = bind.html;
+        let props: string[];
+        let activeCtrl = ctrl;
 
-            if (typeof next !== 'string') {
-                next = '';
+        if (htmlPath.includes(':')) {
+            const [controller, path] = htmlPath.split(':');
+            if (!controller) {
+                console.warn(`[ez] Invalid bind.html format: ${htmlPath}`);
+                return;
             }
+            activeCtrl = controller;
+            props = path.split('.');
+        } else {
+            props = htmlPath.split('.');
+        }
+
+        const stop = effect(() => {
+            const next = (
+                props.length === 1
+                    ? ez._controllers[activeCtrl!]?.state[props[0]]
+                    : ez.getDeepValue(ez._controllers[activeCtrl!]?.state, props)
+            ) as string;
 
-            el.innerHTML = next;
+            const content = String(next ?? '');
+            el.innerHTML = shouldSanitize ? sanitizeHtml(content) : content;
         });
 
         this._effects!.push(stop);
     }
 
-    private _applyStyleBind(el: HTMLElement, bind: BindConfig): void {
+    private _applyStyleBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
         if (!bind.style) return;
 
         let prevStyles: Record<string, string> = {};
 
-        const stop = effect(() => {
-            let next = bind.style;
+        // If style is a function, call it reactively
+        if (typeof bind.style === 'function') {
+            const stop = effect(() => {
+                const next = (bind.style as () => Record<string, string>)() || {};
 
-            if (typeof next === 'function') {
-                next = next();
-            }
+                for (const key of Object.keys(prevStyles)) {
+                    if (!(key in next)) {
+                        (el.style as unknown as Record<string, string>)[key] = '';
+                    }
+                }
+                for (const [key, value] of Object.entries(next)) {
+                    (el.style as unknown as Record<string, string>)[key] = value;
+                }
+                prevStyles = { ...next };
+            });
+            this._effects!.push(stop);
+            return;
+        }
+
+        // If style is a string, treat it as a state path to a style object
+        const stylePath = bind.style as unknown as string;
+        if (typeof stylePath !== 'string') return;
 
-            if (typeof next !== 'object' || next === null) {
-                next = {};
+        let props: string[];
+        let activeCtrl = ctrl;
+
+        if (stylePath.includes(':')) {
+            const [controller, path] = stylePath.split(':');
+            if (!controller) {
+                console.warn(`[ez] Invalid bind.style format: ${stylePath}`);
+                return;
             }
+            activeCtrl = controller;
+            props = path.split('.');
+        } else {
+            props = stylePath.split('.');
+        }
+
+        const stop = effect(() => {
+            const next = (
+                props.length === 1
+                    ? ez._controllers[activeCtrl!]?.state[props[0]]
+                    : ez.getDeepValue(ez._controllers[activeCtrl!]?.state, props)
+            ) as Record<string, string> || {};
 
-            // Remove previous styles that are not in the new object
             for (const key of Object.keys(prevStyles)) {
                 if (!(key in next)) {
                     (el.style as unknown as Record<string, string>)[key] = '';
                 }
             }
-
-            // Apply new styles (supports camelCase like 'backgroundColor')
             for (const [key, value] of Object.entries(next)) {
                 (el.style as unknown as Record<string, string>)[key] = value;
             }
-
             prevStyles = { ...next };
         });
 
         this._effects!.push(stop);
     }
 
-    private _applyTextBind(el: HTMLElement, bind: BindConfig): void {
+    private _applyTextBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
         if (!bind.text) return;
 
-        const stop = effect(() => {
-            let next = bind.text;
+        // If text is a function, call it reactively
+        if (typeof bind.text === 'function') {
+            const stop = effect(() => {
+                const next = (bind.text as () => string)();
+                el.textContent = String(next ?? '');
+            });
+            this._effects!.push(stop);
+            return;
+        }
 
-            if (typeof next === 'function') {
-                next = next();
-            }
+        // If text is a string, treat it as a state path (like 'prop' or 'Controller:prop')
+        const textPath = bind.text;
+        let props: string[] | undefined;
+        let activeCtrl = ctrl;
 
-            if (typeof next !== 'string') {
-                next = String(next ?? '');
+        if (textPath.includes(':')) {
+            const [controller, path] = textPath.split(':');
+            props = path?.split('.');
+            if (!controller) {
+                console.warn(`[ez] Invalid bind.text format: ${textPath}`);
+                return;
             }
+            activeCtrl = controller;
+        } else {
+            props = textPath.split('.');
+        }
 
-            el.textContent = next;
-        });
+        const stop = effect(() => {
+            const next =
+                props?.length === 1
+                    ? ez._controllers[activeCtrl!]?.state[props[0]]
+                    : ez.getDeepValue(ez._controllers[activeCtrl!]?.state, props!);
 
+            el.textContent = String(next ?? '');
+        });
         this._effects!.push(stop);
     }
 
@@ -674,89 +882,132 @@ export class EzBaseComponent {
     }
 
     /**
-     * Apply tooltip if configured
+     * Apply tooltip if configured.
+     * Tooltip is created lazily on first hover to avoid DOM pollution.
+     * Supports text tooltips: tooltip: "Hello" or tooltip: { text: "Hello" }
+     * Supports component tooltips: tooltip: { component: { eztype: 'MyCard', props: {...} } }
      */
     applyTooltip(el: HTMLElement): void {
         const tipConfig = this.config.tooltip;
         if (!tipConfig) return;
 
-        const text = typeof tipConfig === 'string' ? tipConfig : tipConfig.text;
+        const isString = typeof tipConfig === 'string';
+        const text = isString ? tipConfig : tipConfig.text;
+        const componentConfig = isString ? null : tipConfig.component;
         const position: TooltipPosition = (typeof tipConfig === 'object' ? tipConfig.position : null) || 'top';
         const variant: TooltipVariant = (typeof tipConfig === 'object' ? tipConfig.variant : null) || 'dark';
         const delay = (typeof tipConfig === 'object' ? tipConfig.delay : null) ?? 200;
 
-        if (!text) return;
+        if (!text && !componentConfig) return;
 
-        const tooltip = document.createElement('div');
-        tooltip.className = tooltipCls('tooltip', variant);
-        tooltip.textContent = text;
-        tooltip.style.opacity = '0';
-        tooltip.style.visibility = 'hidden';
+        const isComponentTooltip = !!componentConfig;
+        let tooltip: HTMLDivElement | null = null;
+        let showTimeout: ReturnType<typeof setTimeout> | null = null;
+        let hideTimeout: ReturnType<typeof setTimeout> | null = null;
+        let componentRendered = false;
+
+        const createTooltip = (): HTMLDivElement => {
+            const tip = document.createElement('div');
+            tip.className = tooltipCls('tooltip', isComponentTooltip ? 'component' : variant);
+            tip.style.opacity = '0';
+            tip.style.visibility = 'hidden';
+
+            if (text && !componentConfig) {
+                tip.textContent = text;
+                const arrow = document.createElement('div');
+                arrow.className = tooltipCls('arrow');
+                tip.appendChild(arrow);
+            }
+
+            document.body.appendChild(tip);
+            return tip;
+        };
 
-        const arrow = document.createElement('div');
-        arrow.className = tooltipCls('arrow');
-        tooltip.appendChild(arrow);
+        const positionTooltip = (): void => {
+            if (!tooltip) return;
+            const rect = el.getBoundingClientRect();
+            const tooltipRect = tooltip.getBoundingClientRect();
+
+            let top: number;
+            let 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;
+            }
 
-        document.body.appendChild(tooltip);
+            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;
+            }
 
-        let showTimeout: ReturnType<typeof setTimeout> | null = null;
-        let hideTimeout: ReturnType<typeof setTimeout> | null = null;
+            tooltip.style.top = `${top + window.scrollY}px`;
+            tooltip.style.left = `${left + window.scrollX}px`;
+            tooltip.className = tooltipCls('tooltip', isComponentTooltip ? 'component' : variant, position);
+        };
 
         const showTooltip = (): void => {
             if (hideTimeout) clearTimeout(hideTimeout);
-            showTimeout = setTimeout(() => {
-                const rect = el.getBoundingClientRect();
-                const tooltipRect = tooltip.getBoundingClientRect();
-
-                let top: number;
-                let 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;
+            showTimeout = setTimeout(async () => {
+                // Lazy create tooltip on first hover
+                if (!tooltip) {
+                    tooltip = createTooltip();
+                    this._tooltip = tooltip;
                 }
 
-                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;
+                if (componentConfig && !componentRendered) {
+                    const componentEl = await ez._createElement(componentConfig);
+                    tooltip.appendChild(componentEl);
+                    componentRendered = true;
+                    requestAnimationFrame(() => {
+                        positionTooltip();
+                        if (tooltip) {
+                            tooltip.style.opacity = '1';
+                            tooltip.style.visibility = 'visible';
+                        }
+                    });
+                } else {
+                    positionTooltip();
+                    if (tooltip) {
+                        tooltip.style.opacity = '1';
+                        tooltip.style.visibility = 'visible';
+                    }
                 }
-
-                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);
+                if (tooltip?.parentNode) {
+                    tooltip.parentNode.removeChild(tooltip);
+                    tooltip = null;
+                    this._tooltip = undefined;
+                    componentRendered = false;
+                }
+            }, 150); // Small delay for smooth transition
         };
 
         el.addEventListener('mouseenter', showTooltip);
@@ -764,7 +1015,6 @@ export class EzBaseComponent {
         el.addEventListener('focus', showTooltip);
         el.addEventListener('blur', hideTooltip);
 
-        this._tooltip = tooltip;
         this._tooltipCleanup = () => {
             if (showTimeout) clearTimeout(showTimeout);
             if (hideTimeout) clearTimeout(hideTimeout);
@@ -772,12 +1022,57 @@ export class EzBaseComponent {
             el.removeEventListener('mouseleave', hideTooltip);
             el.removeEventListener('focus', showTooltip);
             el.removeEventListener('blur', hideTooltip);
-            if (tooltip.parentNode) {
+            if (tooltip?.parentNode) {
                 tooltip.parentNode.removeChild(tooltip);
             }
+            tooltip = null;
         };
     }
 
+    /**
+     * Apply showOnHover behavior.
+     * Element is hidden by default and revealed when parent is hovered.
+     * Must be called AFTER element is added to DOM (needs parentElement).
+     */
+    applyShowOnHover(el: HTMLElement): void {
+        if (!this.config.showOnHover) return;
+
+        // Set initial hidden state
+        el.style.opacity = '0';
+        el.style.visibility = 'hidden';
+        el.style.transition = 'opacity 0.15s ease, visibility 0.15s ease';
+
+        // Defer to next frame to ensure element is in DOM
+        requestAnimationFrame(() => {
+            const parent = el.parentElement;
+            if (!parent) return;
+
+            // Ensure parent has position for absolute children if needed
+            const parentPosition = getComputedStyle(parent).position;
+            if (parentPosition === 'static') {
+                parent.style.position = 'relative';
+            }
+
+            const show = () => {
+                el.style.opacity = '1';
+                el.style.visibility = 'visible';
+            };
+
+            const hide = () => {
+                el.style.opacity = '0';
+                el.style.visibility = 'hidden';
+            };
+
+            parent.addEventListener('mouseenter', show);
+            parent.addEventListener('mouseleave', hide);
+
+            this._showOnHoverCleanup = () => {
+                parent.removeEventListener('mouseenter', show);
+                parent.removeEventListener('mouseleave', hide);
+            };
+        });
+    }
+
     destroy(): void {
         // Destroy children first
         if (this._children) {
@@ -803,6 +1098,15 @@ export class EzBaseComponent {
             this._tooltipCleanup();
         }
 
+        if (this._showOnHoverCleanup) {
+            this._showOnHoverCleanup();
+        }
+
+        if (this._activateHandler && this.el) {
+            this.el.removeEventListener('ez-activate', this._activateHandler);
+            this._activateHandler = undefined;
+        }
+
         if (this.el) {
             (this.el as HTMLElement & { __ezInstance: unknown }).__ezInstance = null;
             this.el = null;