ezfw-core 1.0.0

package/components/EzBaseComponent.ts

@@ -0,0 +1,648 @@
+import { effect } from '@preact/signals';
+import tooltipStyles from './tooltip/EzTooltip.module.scss';
+import { cx } from '../utils/cssModules.js';
+
+const tooltipCls = cx(tooltipStyles);
+
+// ==========================================================
+// Type Definitions
+// ==========================================================
+
+declare const ez: {
+    _controllers: Record<string, EzController | undefined>;
+    getController(name: string): EzController | null;
+    getDeepValue(obj: unknown, path: string[]): unknown;
+    setDeepValue(obj: unknown, path: string[], value: unknown): void;
+    _createElement(config: EzComponentConfig): Promise<HTMLElement>;
+};
+
+interface EzController {
+    state: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+interface StyleModule {
+    [className: string]: string;
+}
+
+type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+type TooltipVariant = 'dark' | 'light';
+
+interface TooltipConfig {
+    text: string;
+    position?: TooltipPosition;
+    variant?: TooltipVariant;
+    delay?: number;
+}
+
+interface BindConfig {
+    value?: string;
+    data?: string;
+    visible?: string;
+    cls?: string | (() => string);
+    html?: string | (() => string);
+}
+
+export interface EzComponentConfig {
+    controller?: string | null;
+    bind?: string | BindConfig;
+    text?: string | number;
+    cls?: string | string[];
+    style?: Partial<CSSStyleDeclaration>;
+    tooltip?: string | TooltipConfig;
+    props?: Record<string, unknown>;
+    css?: string | unknown;
+    _styleModule?: StyleModule;
+    onChange?: string | ((value: unknown) => void);
+    itemRender?: (item: unknown, index: number, meta: ItemRenderMeta) => EzComponentConfig | null;
+    [key: string]: unknown;
+}
+
+// Alias for component configs
+export type EzBaseComponentConfig = EzComponentConfig;
+
+interface ItemRenderMeta {
+    isFirst: boolean;
+    isLast: boolean;
+    isEven: boolean;
+}
+
+interface ResolvedBinding {
+    controller: EzController;
+    path: string[];
+}
+
+type EffectCleanup = () => void;
+type DomListenerCleanup = () => void;
+
+// ==========================================================
+// EzBaseComponent Class
+// ==========================================================
+
+export class EzBaseComponent {
+    config: EzComponentConfig;
+    props: Record<string, unknown>;
+    el: HTMLElement | null = null;
+
+    protected _effects?: EffectCleanup[];
+    protected _domListeners?: DomListenerCleanup[];
+    protected _children?: EzBaseComponent[];
+    protected _tooltip?: HTMLDivElement;
+    protected _tooltipCleanup?: () => void;
+
+    constructor(config: EzComponentConfig = {}) {
+        this.config = config;
+        this.props = config.props || {};
+    }
+
+    /**
+     * Resolve binding configuration to get controller and path.
+     * Supports:
+     * - String: "form.username" or "ControllerName:form.username"
+     * - Object: { value: "form.username" }
+     */
+    protected _resolveBinding(): ResolvedBinding | null {
+        const bind = this.config.bind;
+        if (!bind) return null;
+
+        const bindStr = typeof bind === 'string' ? bind : bind.value;
+        if (!bindStr) return null;
+
+        let controllerName: string | undefined;
+        let pathStr: string;
+
+        if (bindStr.includes(':')) {
+            [controllerName, pathStr] = bindStr.split(':');
+        } else {
+            controllerName = this.config.controller ?? undefined;
+            pathStr = bindStr;
+        }
+
+        if (!controllerName) return null;
+
+        const controller = ez.getController(controllerName);
+        if (!controller?.state) return null;
+
+        return {
+            controller,
+            path: pathStr.split('.')
+        };
+    }
+
+    /**
+     * Create onChange handler from config or binding.
+     * Priority: function > string method name > auto from binding
+     */
+    protected _createOnChangeHandler(): ((value: unknown) => void) | null {
+        if (typeof this.config.onChange === 'function') {
+            return this.config.onChange;
+        }
+
+        if (typeof this.config.onChange === 'string') {
+            const controller = ez.getController(this.config.controller ?? '');
+            const method = controller?.[this.config.onChange];
+            if (typeof method === 'function') {
+                return (method as (value: unknown) => void).bind(controller);
+            }
+            return null;
+        }
+
+        const binding = this._resolveBinding();
+        if (binding) {
+            return (value: unknown) => {
+                ez.setDeepValue(binding.controller.state, binding.path, value);
+            };
+        }
+
+        return null;
+    }
+
+    applyCommonBindings(el: HTMLElement): void {
+        this._effects ??= [];
+
+        const bind = this.config.bind;
+        let ctrl: string | undefined = this.config.controller ?? undefined;
+
+        // 1️⃣ Default text
+        if (this.config.text !== undefined && !bind) {
+            el.textContent = String(this.config.text);
+        }
+
+        if (!this.config.bind) return;
+
+        const isInput =
+            el.tagName === 'INPUT' ||
+            el.tagName === 'TEXTAREA' ||
+            el.tagName === 'SELECT';
+
+        // 2️⃣ String bind: 'AppController:prop'
+        if (typeof bind === 'string') {
+            let props: string[] | undefined;
+            if (bind.includes(':')) {
+                const [controller, path] = bind.split(':');
+                props = path?.split('.');
+
+                if (!controller) {
+                    console.warn(`[ez] Invalid bind format: ${bind}`);
+                    return;
+                }
+
+                ctrl = controller;
+            } else {
+                props = bind.split('.');
+            }
+
+            const stop = effect(() => {
+                const next =
+                    props?.length === 1
+                        ? ez._controllers[ctrl!]?.state[props[0]]
+                        : ez.getDeepValue(ez._controllers[ctrl!]?.state, props!);
+
+                const nextStr = (next as string) ?? '';
+                if (isInput) {
+                    if ((el as HTMLInputElement).value !== nextStr) {
+                        (el as HTMLInputElement).value = nextStr;
+                    }
+                } else {
+                    if (el.textContent !== nextStr) {
+                        el.textContent = nextStr;
+                    }
+                }
+            });
+            this._effects.push(stop);
+        }
+
+        // 3️⃣ Object bind
+        if (typeof bind === 'object') {
+            this._applyValueBind(el, bind, ctrl, isInput);
+            this._applyDataBind(el, bind, ctrl);
+            this._applyVisibleBind(el, bind);
+            this._applyClsBind(el, bind);
+            this._applyHtmlBind(el, bind);
+        }
+    }
+
+    private _applyValueBind(
+        el: HTMLElement,
+        bind: BindConfig,
+        ctrl: string | undefined,
+        isInput: boolean
+    ): void {
+        if (!bind.value) return;
+
+        let props: string[] | undefined;
+        let activeCtrl = ctrl;
+
+        if (bind.value.includes(':')) {
+            const [controller, path] = bind.value.split(':');
+            props = path?.split('.');
+
+            if (!controller) {
+                console.warn(`[ez] Invalid bind format: ${bind.value}`);
+                return;
+            }
+
+            activeCtrl = controller;
+        } else {
+            props = bind.value.split('.');
+        }
+
+        const stop = effect(() => {
+            const next =
+                props?.length === 1
+                    ? ez._controllers[activeCtrl!]?.state[props[0]]
+                    : ez.getDeepValue(ez._controllers[activeCtrl!]?.state, props!);
+
+            const nextStr = (next as string) ?? '';
+            if (isInput) {
+                if ((el as HTMLInputElement).value !== nextStr) {
+                    (el as HTMLInputElement).value = nextStr;
+                }
+            } else {
+                if (el.textContent !== nextStr) {
+                    el.textContent = nextStr;
+                }
+            }
+        });
+        this._effects!.push(stop);
+    }
+
+    private _applyDataBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
+        if (!bind.data) return;
+
+        let props: string[] | undefined;
+        let activeCtrl = ctrl;
+
+        if (bind.data.includes(':')) {
+            const [controller, path] = bind.data.split(':');
+            props = path?.split('.');
+
+            if (!controller) {
+                console.warn(`[ez] Invalid bind format: ${bind.data}`);
+                return;
+            }
+
+            activeCtrl = controller;
+        } else {
+            props = bind.data.split('.');
+        }
+
+        const stop = effect(() => {
+            (async () => {
+                const itemFn = this.config.itemRender;
+                let data = ez.getDeepValue(ez.getController(activeCtrl!)?.state, props!) as unknown[] | unknown;
+
+                if (data == null) {
+                    return;
+                }
+
+                if (!Array.isArray(data)) {
+                    data = [data];
+                }
+
+                el.innerHTML = '';
+
+                if (Array.isArray(data)) {
+                    (el as HTMLElement & { _ezListConfig: unknown })._ezListConfig = { ctrl: activeCtrl, props, itemFn };
+                    (el as HTMLElement & { _ezListRendered: boolean })._ezListRendered = true;
+                    el.setAttribute("data-ez-list", "true");
+
+                    el.innerHTML = '';
+                    for (let i = 0; i < data.length; i++) {
+                        if (data[i] == null) {
+                            if (import.meta.env.DEV) {
+                                console.warn(`[Ez] bind.data: Item at index ${i} is null/undefined. Controller: "${activeCtrl}", path: "${props!.join('.')}". Skipping.`);
+                            }
+                            continue;
+                        }
+
+                        const isLast = i === data.length - 1;
+                        const isFirst = i === 0;
+                        const isEven = i % 2 === 0;
+
+                        const childCfg = itemFn?.(data[i], i, { isFirst, isLast, isEven });
+
+                        if (!childCfg) continue;
+
+                        if (!childCfg.controller) {
+                            childCfg.controller = activeCtrl;
+                        }
+                        if (!childCfg.css && this.config.css) {
+                            childCfg.css = this.config.css;
+                            childCfg._styleModule = this.config._styleModule;
+                        }
+                        const childEl = await ez._createElement(childCfg);
+                        el.appendChild(childEl);
+                    }
+                }
+            })();
+        });
+        this._effects!.push(stop);
+    }
+
+    private _applyVisibleBind(el: HTMLElement, bind: BindConfig): void {
+        if (!bind.visible) return;
+
+        const expr = bind.visible;
+        el.setAttribute('data-ez-visible', expr);
+
+        interface ParsedVisibility {
+            controllerName: string;
+            props: string[];
+            operator: string;
+            rightExpr: string;
+        }
+
+        function parseVisibilityExpression(expr: string): 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('.');
+
+            return { controllerName, props, operator, rightExpr };
+        }
+
+        const parsed = parseVisibilityExpression(expr);
+
+        if (parsed) {
+            const { controllerName, props, operator, rightExpr } = parsed;
+
+            const stop = effect(() => {
+                const state = ez._controllers[controllerName]?.state;
+                const left = ez.getDeepValue(state, props) as number | string;
+
+                const right = isNaN(Number(rightExpr)) ? rightExpr : Number(rightExpr);
+
+                let result = true;
+                switch (operator) {
+                    case '>': result = left > right; break;
+                    case '<': result = left < right; break;
+                    case '>=': result = left >= right; break;
+                    case '<=': result = left <= right; break;
+                    case '!=': result = left != right; break;
+                    case '==': result = left == right; break;
+                }
+
+                if (result) {
+                    el.style.removeProperty('display');
+                } else {
+                    el.style.setProperty('display', 'none', 'important');
+                }
+            });
+            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;
+            }
+
+            const stop = effect(() => {
+                const result = !!ez.getDeepValue(ez._controllers[controllerName]?.state, props);
+                el.style.display = result ? '' : 'none';
+            });
+            this._effects!.push(stop);
+
+        } else {
+            console.warn(`[ez] Unsupported visibility expression: ${expr}`);
+        }
+    }
+
+    private _applyClsBind(el: HTMLElement, bind: BindConfig): void {
+        if (!bind.cls) return;
+
+        let prevClasses: string[] = [];
+        const styleModule = this.config._styleModule;
+
+        const stop = effect(() => {
+            let next = bind.cls;
+
+            if (typeof next === 'function') {
+                next = next();
+            }
+
+            if (typeof next !== 'string') {
+                next = '';
+            }
+
+            const classes = next.split(' ').filter(Boolean).map(c => {
+                if (styleModule && styleModule[c]) {
+                    return styleModule[c];
+                }
+                return c;
+            });
+
+            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 {
+        if (!bind.html) return;
+
+        const stop = effect(() => {
+            let next = bind.html;
+
+            if (typeof next === 'function') {
+                next = next();
+            }
+
+            if (typeof next !== 'string') {
+                next = '';
+            }
+
+            el.innerHTML = next;
+        });
+
+        this._effects!.push(stop);
+    }
+
+    applyStyles(el: HTMLElement): void {
+        if (this.config.style && typeof this.config.style === 'object') {
+            Object.assign(el.style, this.config.style);
+        }
+    }
+
+    /**
+     * Apply static cls with CSS module resolution
+     */
+    applyCls(el: HTMLElement): void {
+        const cls = this.config.cls;
+        if (!cls) return;
+
+        const styleModule = this.config._styleModule;
+
+        if (Array.isArray(cls)) {
+            const resolvedClasses = cls.map(c => {
+                if (styleModule && typeof c === 'string' && styleModule[c]) {
+                    return styleModule[c];
+                }
+                return c;
+            }).filter(Boolean) as string[];
+            if (resolvedClasses.length) {
+                el.classList.add(...resolvedClasses);
+            }
+        } else if (typeof cls === 'string') {
+            const classes = cls.split(' ').filter(Boolean).map(c => {
+                if (styleModule && styleModule[c]) {
+                    return styleModule[c];
+                }
+                return c;
+            });
+            if (classes.length) {
+                el.classList.add(...classes);
+            }
+        }
+    }
+
+    /**
+     * Apply tooltip if configured
+     */
+    applyTooltip(el: HTMLElement): void {
+        const tipConfig = this.config.tooltip;
+        if (!tipConfig) return;
+
+        const text = typeof tipConfig === 'string' ? tipConfig : tipConfig.text;
+        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;
+
+        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;
+                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;
+                }
+
+                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);
+
+        this._tooltip = tooltip;
+        this._tooltipCleanup = () => {
+            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);
+            }
+        };
+    }
+
+    destroy(): void {
+        // Destroy children first
+        if (this._children) {
+            for (const child of this._children) {
+                if (child && typeof child.destroy === 'function') {
+                    child.destroy();
+                }
+            }
+            this._children = [];
+        }
+
+        if (this._effects) {
+            for (const stop of this._effects) stop();
+            this._effects = [];
+        }
+
+        if (this._domListeners) {
+            this._domListeners.forEach(off => off());
+            this._domListeners = [];
+        }
+
+        if (this._tooltipCleanup) {
+            this._tooltipCleanup();
+        }
+
+        if (this.el) {
+            (this.el as HTMLElement & { __ezInstance: unknown }).__ezInstance = null;
+            this.el = null;
+        }
+    }
+}