ezfw-core 1.0.87 → 1.0.88

package/README.md

@@ -126,7 +126,7 @@ ez.route('/users/:id', 'UserDetail');
 }
 
 // In controller
-const form = ez._refs.myForm;
+const form = ez.refs.myForm;
 if (form.validate()) {
     const data = form.getFormData();
 }

package/components/EzBaseComponent.ts

@@ -58,7 +58,10 @@ interface BindConfig {
     visible?: string;
     cls?: string | (() => string);
     html?: string | (() => string);
+    /** @deprecated Use allowUnsafeHtml instead. Kept for backwards compatibility. */
     sanitizeHtml?: boolean;
+    /** Set to true to skip HTML sanitization. Use only for trusted content (e.g., markdown libraries that sanitize internally). */
+    allowUnsafeHtml?: boolean;
     style?: Record<string, string> | (() => Record<string, string>);
     text?: string | (() => string);
     [key: string]: unknown;
@@ -70,8 +73,86 @@ function sanitizeHtml(html: string): string {
     return div.innerHTML;
 }
 
+/**
+ * Shallow comparison of two objects
+ */
+function shallowEqual(objA: Record<string, unknown>, objB: Record<string, unknown>): boolean {
+    if (objA === objB) return true;
+    if (!objA || !objB) return false;
+
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+
+    if (keysA.length !== keysB.length) return false;
+
+    for (const key of keysA) {
+        if (objA[key] !== objB[key]) return false;
+    }
+
+    return true;
+}
+
+/**
+ * Compare only specific keys of two objects
+ */
+function shallowEqualKeys(objA: Record<string, unknown>, objB: Record<string, unknown>, keys: string[]): boolean {
+    if (objA === objB) return true;
+    if (!objA || !objB) return false;
+
+    for (const key of keys) {
+        if (objA[key] !== objB[key]) return false;
+    }
+
+    return true;
+}
+
+/**
+ * Check if component should update based on memo/shouldUpdate config
+ * @returns true if should re-render, false to skip
+ */
+export function checkShouldUpdate(
+    config: EzComponentConfig,
+    prevProps: Record<string, unknown> | undefined,
+    nextProps: Record<string, unknown>
+): boolean {
+    // No previous props = first render, always render
+    if (!prevProps) return true;
+
+    // Custom shouldUpdate function takes priority
+    if (typeof config.shouldUpdate === 'function') {
+        return config.shouldUpdate(prevProps, nextProps);
+    }
+
+    // memo: true = shallow equal all props
+    if (config.memo === true) {
+        return !shallowEqual(prevProps, nextProps);
+    }
+
+    // memo: ['prop1', 'prop2'] = shallow equal specific props
+    if (Array.isArray(config.memo)) {
+        return !shallowEqualKeys(prevProps, nextProps, config.memo);
+    }
+
+    // No memoization configured = always re-render
+    return true;
+}
+
 type StyleValue = string | number | undefined;
 
+/**
+ * Prop validation schema for component props
+ */
+export interface PropDef {
+    /** Whether this prop is required */
+    required?: boolean;
+    /** Expected type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function' */
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function';
+    /** Default value if prop is not provided */
+    default?: unknown;
+}
+
+export type PropSchema = Record<string, PropDef>;
+
 export interface EzComponentConfig {
     controller?: string | null;
     bind?: string | BindConfig;
@@ -80,11 +161,19 @@ export interface EzComponentConfig {
     style?: Partial<CSSStyleDeclaration>;
     tooltip?: string | TooltipConfig;
     props?: Record<string, unknown>;
+    /** Prop validation schema */
+    propTypes?: PropSchema;
     css?: string | unknown;
     _styleModule?: StyleModule;
     onChange?: string | ((value: unknown) => void);
     itemRender?: (item: unknown, index: number, meta: ItemRenderMeta) => EzComponentConfig | null;
 
+    // Event delegation for lists (used with bind.data + itemRender)
+    // These handlers receive: (event, item, index)
+    onItemClick?: string;
+    onItemDoubleClick?: string;
+    onItemContextMenu?: string;
+
     // Style shortcuts - Spacing
     p?: StyleValue;
     pt?: StyleValue;
@@ -154,6 +243,28 @@ export interface EzComponentConfig {
     // Behavior shortcuts
     showOnHover?: boolean;
 
+    /**
+     * Memoization: If true, component will skip re-render when props are shallowly equal.
+     * Can also be an array of prop names to compare (e.g., ['user', 'isActive']).
+     * For custom comparison logic, use shouldUpdate instead.
+     */
+    memo?: boolean | string[];
+
+    /**
+     * Custom function to determine if component should re-render.
+     * Return true to re-render, false to skip.
+     * @param prevProps - Previous props object
+     * @param nextProps - New props object
+     * @returns boolean - true to re-render, false to skip
+     */
+    shouldUpdate?: (prevProps: Record<string, unknown>, nextProps: Record<string, unknown>) => boolean;
+
+    /**
+     * Internal: Stores previous props for memoization comparison.
+     * @internal
+     */
+    _prevProps?: Record<string, unknown>;
+
     [key: string]: unknown;
 }
 
@@ -187,6 +298,10 @@ export class EzBaseComponent {
     protected _effects?: EffectCleanup[];
     protected _domListeners?: DomListenerCleanup[];
     protected _children?: EzBaseComponent[];
+    protected _keyedChildren?: Map<string | number, { instance: EzBaseComponent; element: HTMLElement; dataHash: string; prevProps?: Record<string, unknown> }>;
+    protected _lastKeyWarning?: number;
+    protected _listData?: unknown[];
+    protected _listDelegatedEvents?: boolean;
     protected _tooltip?: HTMLDivElement;
     protected _tooltipCleanup?: () => void;
     protected _activateHandler?: (e: Event) => void;
@@ -463,76 +578,319 @@ export class EzBaseComponent {
                     data = [data];
                 }
 
+                // Cast to array for TypeScript
+                const dataArray = data as unknown[];
+
                 // 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);
+                // Generate all configs first to check for keys
+                const configs: Array<EzComponentConfig & { key?: string | number; _itemData?: unknown }> = [];
+                for (let i = 0; i < dataArray.length; i++) {
+                    if (dataArray[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;
                     }
-                    for (const child of childrenToRemove) {
-                        child.destroy();
-                        const idx = this._children.indexOf(child);
-                        if (idx !== -1) this._children.splice(idx, 1);
+
+                    const isLast = i === dataArray.length - 1;
+                    const isFirst = i === 0;
+                    const isEven = i % 2 === 0;
+
+                    const childCfg = itemFn?.(dataArray[i], i, { isFirst, isLast, isEven });
+                    if (childCfg) {
+                        // Store original data for comparison in key-based reconciliation
+                        childCfg._itemData = dataArray[i];
+                        // Add data-ez-index for event delegation
+                        const existingAttrs = (childCfg.attrs as Record<string, unknown>) || {};
+                        childCfg.attrs = { ...existingAttrs, 'data-ez-index': String(i) };
+                        configs.push(childCfg);
+                    }
+                }
+
+                // Check if configs have keys
+                const hasKeys = configs.length > 0 && configs[0].key !== undefined;
+
+                // Dev warning for large lists without keys
+                if (import.meta.env.DEV && !hasKeys && configs.length > 50) {
+                    const now = Date.now();
+                    // Only warn once per 5 seconds to avoid spam
+                    if (!this._lastKeyWarning || now - this._lastKeyWarning > 5000) {
+                        this._lastKeyWarning = now;
+                        const componentName = this.config.eztype || this.constructor.name || 'Unknown';
+                        console.warn(
+                            `%c[EZ Performance]%c List with ${configs.length} items rendered without keys.\n\n` +
+                            `Consider adding a "key" property to itemRender for better performance:\n\n` +
+                            `  itemRender: (item) => ({\n` +
+                            `    key: item.id,  // ← Add unique identifier\n` +
+                            `    eztype: '...',\n` +
+                            `    props: { item }\n` +
+                            `  })\n\n` +
+                            `Component: ${componentName}\n` +
+                            `Controller: ${activeCtrl}\n` +
+                            `Data path: ${props!.join('.')}`,
+                            'background: #f59e0b; color: #000; padding: 2px 6px; border-radius: 3px; font-weight: bold;',
+                            'color: #f59e0b;'
+                        );
                     }
                 }
 
-                el.innerHTML = '';
+                // Set list markers
+                (el as HTMLElement & { _ezListConfig: unknown })._ezListConfig = { ctrl: activeCtrl, props, itemFn };
+                (el as HTMLElement & { _ezListRendered: boolean })._ezListRendered = true;
+                el.setAttribute("data-ez-list", "true");
 
-                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");
+                // Store data for event delegation handlers
+                this._listData = dataArray;
 
-                    for (let i = 0; i < data.length; i++) {
-                        // Check if render is still current before each iteration
-                        if (renderVersion !== currentRenderVersion) return;
+                // Setup event delegation (only once)
+                if (!this._listDelegatedEvents) {
+                    this._setupListEventDelegation(el, activeCtrl);
+                    this._listDelegatedEvents = true;
+                }
 
-                        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;
-                        }
+                if (hasKeys) {
+                    // Key-based reconciliation
+                    await this._reconcileWithKeys(el, configs, activeCtrl, renderVersion, () => renderVersion !== currentRenderVersion);
+                } else {
+                    // Full re-render (original behavior)
+                    await this._fullRerender(el, configs, activeCtrl, renderVersion, () => renderVersion !== currentRenderVersion);
+                }
+            })();
+        });
+        this._effects!.push(stop);
+    }
+
+    /**
+     * Key-based reconciliation: Only create/destroy what changed, reuse existing elements
+     */
+    private async _reconcileWithKeys(
+        el: HTMLElement,
+        configs: Array<EzComponentConfig & { key?: string | number; _itemData?: unknown }>,
+        activeCtrl: string | undefined,
+        renderVersion: number,
+        isStale: () => boolean
+    ): Promise<void> {
+        // Initialize keyed children map if needed
+        this._keyedChildren ??= new Map();
+
+        const newKeys = new Set(configs.map(c => c.key!));
+        const oldKeys = new Set(this._keyedChildren.keys());
+
+        // 1. Destroy children that no longer exist
+        for (const key of oldKeys) {
+            if (!newKeys.has(key)) {
+                const child = this._keyedChildren.get(key);
+                if (child) {
+                    child.instance.destroy();
+                    if (this._children) {
+                        const idx = this._children.indexOf(child.instance);
+                        if (idx !== -1) this._children.splice(idx, 1);
+                    }
+                    this._keyedChildren.delete(key);
+                }
+            }
+        }
 
-                        const isLast = i === data.length - 1;
-                        const isFirst = i === 0;
-                        const isEven = i % 2 === 0;
+        // 2. Build new order and create/update elements
+        const newOrder: Array<{ key: string | number; element: HTMLElement; isNew: boolean }> = [];
 
-                        const childCfg = itemFn?.(data[i], i, { isFirst, isLast, isEven });
+        for (const cfg of configs) {
+            if (isStale()) return;
 
-                        if (!childCfg) continue;
+            const key = cfg.key!;
+            const existing = this._keyedChildren.get(key);
+            const newDataHash = JSON.stringify(cfg._itemData);
+            const currentProps = cfg.props || {};
 
-                        if (!childCfg.controller) {
-                            childCfg.controller = activeCtrl;
-                        }
-                        // Only inherit CSS if child doesn't have its own CSS module
-                        const childHasOwnCss = childCfg.css ||
-                            (typeof childCfg.eztype === 'string' && ez.hasStyles(childCfg.eztype));
-                        if (!childHasOwnCss && this.config.css) {
-                            childCfg.css = this.config.css;
-                            childCfg._styleModule = this.config._styleModule;
-                        }
-                        // Propagate _isRepaint to skip onLoad in children during breakpoint repaint
-                        if ((this.config as { _isRepaint?: boolean })._isRepaint) {
-                            (childCfg as { _isRepaint?: boolean })._isRepaint = true;
-                        }
-                        // Pass 'this' as inheritedState so children are added to _children
-                        const childEl = await ez._createElement(childCfg, null, this);
+            // Determine if we should reuse the existing element
+            let shouldReuse = false;
+            if (existing) {
+                // Check memoization: memo/shouldUpdate take priority over dataHash
+                if (cfg.memo !== undefined || cfg.shouldUpdate !== undefined) {
+                    // Use memoization logic
+                    shouldReuse = !checkShouldUpdate(cfg, existing.prevProps, currentProps);
+                } else {
+                    // Default: compare data hash (original behavior)
+                    shouldReuse = existing.dataHash === newDataHash;
+                }
+            }
 
-                        // Final check before appending
-                        if (renderVersion !== currentRenderVersion) return;
+            if (shouldReuse && existing) {
+                // Key exists AND memoization says skip update → reuse element
+                newOrder.push({ key, element: existing.element, isNew: false });
+            } else {
+                // Key doesn't exist OR should update → create new element
 
-                        el.appendChild(childEl);
+                // If key exists but needs update, destroy old first
+                if (existing) {
+                    existing.instance.destroy();
+                    if (this._children) {
+                        const idx = this._children.indexOf(existing.instance);
+                        if (idx !== -1) this._children.splice(idx, 1);
                     }
+                    this._keyedChildren.delete(key);
                 }
-            })();
-        });
-        this._effects!.push(stop);
+
+                // Create new element
+                this._prepareChildConfig(cfg, activeCtrl);
+                const childEl = await ez._createElement(cfg, null, this);
+
+                if (isStale()) return;
+
+                // Find the instance that was just created (last in _children)
+                const instance = this._children?.[this._children.length - 1];
+                if (instance) {
+                    this._keyedChildren.set(key, {
+                        instance,
+                        element: childEl,
+                        dataHash: newDataHash,
+                        prevProps: { ...currentProps }  // Store props for next comparison
+                    });
+                }
+
+                newOrder.push({ key, element: childEl, isNew: true });
+            }
+        }
+
+        // 3. Reorder DOM to match new order
+        // We use a simple algorithm: iterate through newOrder and ensure each element is in the right position
+        let currentNode = el.firstChild as HTMLElement | null;
+
+        for (const item of newOrder) {
+            if (isStale()) return;
+
+            if (currentNode === item.element) {
+                // Already in correct position
+                currentNode = currentNode.nextSibling as HTMLElement | null;
+            } else if (item.isNew || !el.contains(item.element)) {
+                // New element or not in DOM yet - insert before currentNode
+                el.insertBefore(item.element, currentNode);
+            } else {
+                // Existing element in wrong position - move it
+                el.insertBefore(item.element, currentNode);
+            }
+        }
+    }
+
+    /**
+     * Full re-render: Destroy all and recreate (original behavior)
+     */
+    private async _fullRerender(
+        el: HTMLElement,
+        configs: EzComponentConfig[],
+        activeCtrl: string | undefined,
+        renderVersion: number,
+        isStale: () => boolean
+    ): Promise<void> {
+        // Clear keyed children if switching from keyed to non-keyed
+        if (this._keyedChildren) {
+            this._keyedChildren.clear();
+        }
+
+        // Destroy old children before clearing
+        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 = '';
+
+        // Create all children
+        for (const cfg of configs) {
+            if (isStale()) return;
+
+            this._prepareChildConfig(cfg, activeCtrl);
+            const childEl = await ez._createElement(cfg, null, this);
+
+            if (isStale()) return;
+
+            el.appendChild(childEl);
+        }
+    }
+
+    /**
+     * Prepare child config with inherited controller and CSS
+     */
+    private _prepareChildConfig(cfg: EzComponentConfig, activeCtrl: string | undefined): void {
+        if (!cfg.controller) {
+            cfg.controller = activeCtrl;
+        }
+        // Only inherit CSS if child doesn't have its own CSS module
+        const childHasOwnCss = cfg.css ||
+            (typeof cfg.eztype === 'string' && ez.hasStyles(cfg.eztype));
+        if (!childHasOwnCss && this.config.css) {
+            cfg.css = this.config.css;
+            cfg._styleModule = this.config._styleModule;
+        }
+        // Propagate _isRepaint to skip onLoad in children during breakpoint repaint
+        if ((this.config as { _isRepaint?: boolean })._isRepaint) {
+            (cfg as { _isRepaint?: boolean })._isRepaint = true;
+        }
+    }
+
+    /**
+     * Setup event delegation for list items
+     * Instead of N listeners (one per item), uses 1 listener on the container
+     */
+    private _setupListEventDelegation(el: HTMLElement, activeCtrl: string | undefined): void {
+        const delegatedEvents: Array<{ event: string; handler: string }> = [];
+
+        if (this.config.onItemClick) {
+            delegatedEvents.push({ event: 'click', handler: this.config.onItemClick });
+        }
+        if (this.config.onItemDoubleClick) {
+            delegatedEvents.push({ event: 'dblclick', handler: this.config.onItemDoubleClick });
+        }
+        if (this.config.onItemContextMenu) {
+            delegatedEvents.push({ event: 'contextmenu', handler: this.config.onItemContextMenu });
+        }
+
+        if (delegatedEvents.length === 0) return;
+
+        for (const { event, handler } of delegatedEvents) {
+            const listener = (e: Event) => {
+                // Find the closest element with data-ez-index
+                const target = e.target as HTMLElement;
+                const itemEl = target.closest('[data-ez-index]') as HTMLElement | null;
+
+                if (!itemEl || !el.contains(itemEl)) return;
+
+                const indexStr = itemEl.getAttribute('data-ez-index');
+                if (indexStr == null) return;
+
+                const index = parseInt(indexStr, 10);
+                const item = this._listData?.[index];
+
+                if (item === undefined) return;
+
+                // Call the controller method
+                const ctrl = activeCtrl ? ez.getControllerSync(activeCtrl) : null;
+                if (ctrl && typeof ctrl[handler] === 'function') {
+                    ctrl[handler](e, item, index);
+                } else if (import.meta.env.DEV) {
+                    console.warn(
+                        `[Ez] Event delegation: Method "${handler}" not found on controller "${activeCtrl}"`
+                    );
+                }
+            };
+
+            el.addEventListener(event, listener);
+
+            // Track for cleanup
+            this._domListeners ??= [];
+            this._domListeners.push(() => el.removeEventListener(event, listener));
+        }
     }
 
     private _applyVisibleBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
@@ -732,7 +1090,9 @@ export class EzBaseComponent {
     private _applyHtmlBind(el: HTMLElement, bind: BindConfig, ctrl: string | undefined): void {
         if (!bind.html) return;
 
-        const shouldSanitize = bind.sanitizeHtml === true;
+        // Sanitize by default for security. Only skip if explicitly opted out.
+        // Legacy: sanitizeHtml: true still works (redundant now, but backwards compatible)
+        const shouldSanitize = bind.allowUnsafeHtml !== true;
 
         // If html is a function, call it reactively
         if (typeof bind.html === 'function') {
@@ -1121,6 +1481,11 @@ export class EzBaseComponent {
     }
 
     destroy(): void {
+        // Cancel pending requests before destroying
+        if (this.controller && typeof (this.controller as EzController & { cancelRequests?: () => void }).cancelRequests === 'function') {
+            (this.controller as EzController & { cancelRequests?: () => void }).cancelRequests!();
+        }
+
         // Call controller onDestroy if exists
         if (this.controller && typeof (this.controller as EzController & { onDestroy?: () => void }).onDestroy === 'function') {
             (this.controller as EzController & { onDestroy?: () => void }).onDestroy!();

package/components/HtmlWrapper.ts

@@ -148,7 +148,16 @@ export class HtmlWrapper extends EzBaseComponent {
         this.applyCommonBindings(el);
         this.applyStyles(el);
 
-        // Layout
+        // Layout - support hbox/vbox for flexbox layouts
+        if (cfg.layout === 'hbox') {
+            el.style.display = 'flex';
+            el.style.flexDirection = 'row';
+        } else if (cfg.layout === 'vbox') {
+            el.style.display = 'flex';
+            el.style.flexDirection = 'column';
+        }
+
+        // Flex and sizing
         if (cfg.flex !== undefined) {
             el.style.flex = String(cfg.flex);
         }