@wsxjs/wsx-core 0.0.19 → 0.0.21

package/src/utils/element-update.ts

@@ -0,0 +1,377 @@
+/**
+ * Element Update Utilities
+ *
+ * Pure functions for fine-grained DOM updates (RFC 0037 Phase 4).
+ * These functions update only changed props and children, avoiding full element recreation.
+ */
+
+import { shouldUseSVGNamespace, getSVGAttributeName } from "./svg-utils";
+import { flattenChildren, type JSXChildren } from "./dom-utils";
+import { setSmartProperty, isFrameworkInternalProp } from "./props-utils";
+import { shouldPreserveElement } from "./element-marking";
+import type { DOMCacheManager } from "../dom-cache-manager";
+
+/**
+ * Removes a property from an element.
+ */
+function removeProp(
+    element: HTMLElement | SVGElement,
+    key: string,
+    oldValue: unknown,
+    tag: string
+): void {
+    const isSVG = shouldUseSVGNamespace(tag);
+
+    // 处理特殊属性
+    if (key === "ref") {
+        // ref 是回调，不需要移除
+        return;
+    }
+
+    if (key === "className" || key === "class") {
+        if (isSVG) {
+            element.removeAttribute("class");
+        } else {
+            (element as HTMLElement).className = "";
+        }
+        return;
+    }
+
+    if (key === "style") {
+        element.removeAttribute("style");
+        return;
+    }
+
+    if (key.startsWith("on") && typeof oldValue === "function") {
+        // 事件监听器：需要移除（但无法获取原始监听器，所以跳过）
+        // 注意：这可能导致内存泄漏，但在实际使用中，事件监听器通常不会变化
+        return;
+    }
+
+    if (key === "value") {
+        if (
+            element instanceof HTMLInputElement ||
+            element instanceof HTMLTextAreaElement ||
+            element instanceof HTMLSelectElement
+        ) {
+            element.value = "";
+        } else {
+            const attributeName = isSVG ? getSVGAttributeName(key) : key;
+            element.removeAttribute(attributeName);
+        }
+        return;
+    }
+
+    // 过滤框架内部属性（不应该从 DOM 移除，因为它们本来就不应该存在）
+    if (isFrameworkInternalProp(key)) {
+        return;
+    }
+
+    // 移除其他属性
+    const attributeName = isSVG ? getSVGAttributeName(key) : key;
+    element.removeAttribute(attributeName);
+
+    // 尝试移除 JavaScript 属性
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        delete (element as any)[key];
+    } catch {
+        // 忽略删除失败
+    }
+}
+
+/**
+ * Applies a single prop to an element (same logic as element-creation.ts).
+ */
+function applySingleProp(
+    element: HTMLElement | SVGElement,
+    key: string,
+    value: unknown,
+    tag: string,
+    isSVG: boolean
+): void {
+    if (value === null || value === undefined || value === false) {
+        return;
+    }
+
+    // 处理ref回调
+    if (key === "ref" && typeof value === "function") {
+        value(element);
+        return;
+    }
+
+    // 处理className和class
+    if (key === "className" || key === "class") {
+        if (isSVG) {
+            element.setAttribute("class", value as string);
+        } else {
+            (element as HTMLElement).className = value as string;
+        }
+        return;
+    }
+
+    // 处理style
+    if (key === "style" && typeof value === "string") {
+        element.setAttribute("style", value);
+        return;
+    }
+
+    // 处理事件监听器
+    if (key.startsWith("on") && typeof value === "function") {
+        const eventName = key.slice(2).toLowerCase();
+        // 注意：这里会重复添加事件监听器，但这是预期的行为
+        // 在实际使用中，事件监听器通常不会频繁变化
+        element.addEventListener(eventName, value as EventListener);
+        return;
+    }
+
+    // 处理布尔属性
+    if (typeof value === "boolean") {
+        if (value) {
+            element.setAttribute(key, "");
+        }
+        return;
+    }
+
+    // 特殊处理 input/textarea/select 的 value 属性
+    if (key === "value") {
+        if (
+            element instanceof HTMLInputElement ||
+            element instanceof HTMLTextAreaElement ||
+            element instanceof HTMLSelectElement
+        ) {
+            element.value = String(value);
+        } else {
+            const attributeName = isSVG ? getSVGAttributeName(key) : key;
+            element.setAttribute(attributeName, String(value));
+        }
+        return;
+    }
+
+    // 过滤框架内部属性（不应该渲染到 DOM）
+    if (isFrameworkInternalProp(key)) {
+        return;
+    }
+
+    // 处理其他属性 - 使用智能属性设置函数
+    setSmartProperty(element, key, value, tag);
+}
+
+/**
+ * Updates element props by comparing old and new props.
+ * Only updates changed properties.
+ */
+export function updateProps(
+    element: HTMLElement | SVGElement,
+    oldProps: Record<string, unknown> | null | undefined,
+    newProps: Record<string, unknown> | null | undefined,
+    tag: string
+): void {
+    const isSVG = shouldUseSVGNamespace(tag);
+    const old = oldProps || {};
+    const new_ = newProps || {};
+
+    // 移除旧属性（在新 props 中不存在的）
+    for (const key in old) {
+        if (!(key in new_)) {
+            removeProp(element, key, old[key], tag);
+        }
+    }
+
+    // 添加/更新新属性（值发生变化的）
+    // 优化：跳过相同值的属性，减少不必要的 DOM 操作
+    for (const key in new_) {
+        const oldValue = old[key];
+        const newValue = new_[key];
+
+        // 快速路径：引用相等，跳过
+        if (oldValue === newValue) {
+            continue;
+        }
+
+        // 深度比较：对于对象和数组，进行浅比较
+        if (
+            typeof oldValue === "object" &&
+            oldValue !== null &&
+            typeof newValue === "object" &&
+            newValue !== null
+        ) {
+            // 浅比较：只比较第一层属性
+            if (JSON.stringify(oldValue) === JSON.stringify(newValue)) {
+                continue;
+            }
+        }
+
+        // 值确实变化了，更新属性
+        applySingleProp(element, key, newValue, tag, isSVG);
+    }
+}
+
+/**
+ * Updates element children by comparing old and new children.
+ * Simple version: only handles same number of children.
+ */
+export function updateChildren(
+    element: HTMLElement | SVGElement,
+    oldChildren: JSXChildren[],
+    newChildren: JSXChildren[]
+): void {
+    const flatOld = flattenChildren(oldChildren);
+    const flatNew = flattenChildren(newChildren);
+
+    // 阶段 4 简化版：只处理相同数量的子节点
+    const minLength = Math.min(flatOld.length, flatNew.length);
+
+    // 更新现有子节点
+    for (let i = 0; i < minLength; i++) {
+        const oldChild = flatOld[i];
+        const newChild = flatNew[i];
+
+        // 如果是文本节点，更新文本内容
+        if (typeof oldChild === "string" || typeof oldChild === "number") {
+            if (typeof newChild === "string" || typeof newChild === "number") {
+                const textNode = element.childNodes[i];
+                if (textNode && textNode.nodeType === Node.TEXT_NODE) {
+                    textNode.textContent = String(newChild);
+                } else {
+                    // 替换为新的文本节点
+                    const newTextNode = document.createTextNode(String(newChild));
+                    if (textNode) {
+                        element.replaceChild(newTextNode, textNode);
+                    } else {
+                        element.appendChild(newTextNode);
+                    }
+                }
+            } else {
+                // 类型变化：替换节点
+                const textNode = element.childNodes[i];
+                if (textNode) {
+                    // 检查是否应该保留旧节点
+                    if (!shouldPreserveElement(textNode)) {
+                        element.removeChild(textNode);
+                    }
+                    // 如果应该保留，不删除（但可能仍需要添加新节点）
+                }
+                if (typeof newChild === "string" || typeof newChild === "number") {
+                    element.appendChild(document.createTextNode(String(newChild)));
+                } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+                    element.appendChild(newChild);
+                } else if (newChild instanceof DocumentFragment) {
+                    element.appendChild(newChild);
+                }
+            }
+        } else if (oldChild instanceof HTMLElement || oldChild instanceof SVGElement) {
+            // 如果是元素节点，检查是否是同一个元素
+            if (newChild === oldChild) {
+                // 同一个元素，不需要更新
+                continue;
+            } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+                // 不同的元素，替换
+                const oldNode = element.childNodes[i];
+                if (oldNode) {
+                    // 检查是否应该保留旧节点
+                    if (!shouldPreserveElement(oldNode)) {
+                        // 只有当新子元素不在当前位置时才替换
+                        if (oldNode !== newChild) {
+                            element.replaceChild(newChild, oldNode);
+                        }
+                    } else {
+                        // 应该保留旧节点，只添加新节点（不替换）
+                        if (newChild.parentNode !== element) {
+                            element.appendChild(newChild);
+                        }
+                    }
+                } else {
+                    if (newChild.parentNode !== element) {
+                        element.appendChild(newChild);
+                    }
+                }
+            } else {
+                // 类型变化：替换节点
+                const oldNode = element.childNodes[i];
+                if (oldNode) {
+                    // 检查是否应该保留旧节点
+                    if (!shouldPreserveElement(oldNode)) {
+                        element.removeChild(oldNode);
+                    }
+                    // 如果应该保留，不删除（但可能仍需要添加新节点）
+                }
+                if (typeof newChild === "string" || typeof newChild === "number") {
+                    element.appendChild(document.createTextNode(String(newChild)));
+                } else if (newChild instanceof DocumentFragment) {
+                    element.appendChild(newChild);
+                }
+            }
+        }
+    }
+
+    // 添加新子节点
+    for (let i = minLength; i < flatNew.length; i++) {
+        const newChild = flatNew[i];
+        if (newChild === null || newChild === undefined || newChild === false) {
+            continue;
+        }
+
+        if (typeof newChild === "string" || typeof newChild === "number") {
+            element.appendChild(document.createTextNode(String(newChild)));
+        } else if (newChild instanceof HTMLElement || newChild instanceof SVGElement) {
+            // 确保子元素正确添加到当前父容器
+            // appendChild 会自动从旧父容器移除并添加到新父容器
+            // 但我们需要确保不重复添加已存在的子元素
+            if (newChild.parentNode !== element) {
+                element.appendChild(newChild);
+            }
+        } else if (newChild instanceof DocumentFragment) {
+            element.appendChild(newChild);
+        }
+    }
+
+    // 移除多余子节点（阶段 5：正确处理元素保留）
+    // 关键：需要跳过"应该保留"的元素（第三方库注入的元素）
+    const nodesToRemove: Node[] = [];
+    for (let i = flatNew.length; i < element.childNodes.length; i++) {
+        const child = element.childNodes[i];
+        if (!shouldPreserveElement(child)) {
+            // 只有不应该保留的节点才添加到移除列表
+            nodesToRemove.push(child);
+        }
+        // 如果应该保留，跳过（不添加到移除列表）
+    }
+
+    // 统一移除（从后往前移除，避免索引变化）
+    for (let i = nodesToRemove.length - 1; i >= 0; i--) {
+        const node = nodesToRemove[i];
+        if (node.parentNode === element) {
+            element.removeChild(node);
+        }
+    }
+}
+
+/**
+ * Updates an element with new props and children.
+ * Stores metadata in cache manager for next update.
+ */
+export function updateElement(
+    element: HTMLElement | SVGElement,
+    newProps: Record<string, unknown> | null,
+    newChildren: JSXChildren[],
+    tag: string,
+    cacheManager: DOMCacheManager
+): void {
+    // 获取旧的元数据
+    const oldMetadata = cacheManager.getMetadata(element);
+    const oldProps = (oldMetadata?.props as Record<string, unknown>) || null;
+    const oldChildren = (oldMetadata?.children as JSXChildren[]) || [];
+
+    // 更新 props
+    updateProps(element, oldProps, newProps, tag);
+
+    // 更新 children
+    updateChildren(element, oldChildren, newChildren);
+
+    // 保存新的元数据
+    cacheManager.setMetadata(element, {
+        props: newProps || {},
+        children: newChildren,
+    });
+}

package/src/utils/props-utils.ts

@@ -0,0 +1,307 @@
+/**
+ * Props Utilities
+ *
+ * Pure functions for handling element properties and attributes (RFC 0037).
+ * These functions implement the HTML First strategy for property setting.
+ */
+
+import { getSVGAttributeName, shouldUseSVGNamespace } from "./svg-utils";
+import { createLogger } from "./logger";
+const logger = createLogger("Props Utilities");
+
+/**
+ * 检查是否是框架内部属性
+ * 这些属性不应该被渲染到 DOM 元素上
+ *
+ * @param key - 属性名
+ * @returns 是否是框架内部属性
+ */
+export function isFrameworkInternalProp(key: string): boolean {
+    // JSX 标准：key 不应该渲染到 DOM
+    if (key === "key") {
+        return true;
+    }
+
+    // 框架内部属性（用于缓存和优化）
+    if (key === "__wsxPositionId" || key === "__wsxIndex") {
+        return true;
+    }
+
+    // 测试辅助属性（不应该渲染到 DOM）
+    if (key === "__testId") {
+        return true;
+    }
+
+    // ref 已经在 applySingleProp 中处理，但这里也标记为内部属性
+    // 确保不会传递到 setSmartProperty
+    if (key === "ref") {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * 检查是否是 HTML 标准属性
+ * HTML First 策略的核心：优先识别标准属性
+ *
+ * @param key - 属性名
+ * @returns 是否是标准 HTML 属性
+ */
+export function isStandardHTMLAttribute(key: string): boolean {
+    // 标准 HTML 属性集合（常见属性）
+    const standardAttributes = new Set([
+        // 全局属性
+        "id",
+        "class",
+        "className",
+        "style",
+        "title",
+        "lang",
+        "dir",
+        "hidden",
+        "tabindex",
+        "accesskey",
+        "contenteditable",
+        "draggable",
+        "spellcheck",
+        "translate",
+        "autocapitalize",
+        "autocorrect",
+        // 表单属性
+        "name",
+        "value",
+        "type",
+        "placeholder",
+        "required",
+        "disabled",
+        "readonly",
+        "checked",
+        "selected",
+        "multiple",
+        "min",
+        "max",
+        "step",
+        "autocomplete",
+        "autofocus",
+        "form",
+        "formaction",
+        "formenctype",
+        "formmethod",
+        "formnovalidate",
+        "formtarget",
+        // 链接属性
+        "href",
+        "target",
+        "rel",
+        "download",
+        "hreflang",
+        "ping",
+        // 媒体属性
+        "src",
+        "alt",
+        "width",
+        "height",
+        "poster",
+        "preload",
+        "controls",
+        "autoplay",
+        "loop",
+        "muted",
+        "playsinline",
+        "crossorigin",
+        // ARIA 属性（部分常见）
+        "role",
+    ]);
+
+    const lowerKey = key.toLowerCase();
+
+    // 检查是否是标准属性
+    if (standardAttributes.has(lowerKey)) {
+        return true;
+    }
+
+    // 检查是否是 data-* 属性（必须使用连字符）
+    // 注意：单独的 "data" 不是标准属性，不在这个列表中
+    // data 可以检查 JavaScript 属性，data-* 只使用 setAttribute
+    if (lowerKey.startsWith("data-")) {
+        return true; // 标准属性，只使用 setAttribute，不检查对象属性
+    }
+
+    // 检查是否是 aria-* 属性
+    if (lowerKey.startsWith("aria-")) {
+        return true;
+    }
+
+    // 检查是否是 SVG 命名空间属性
+    if (key.startsWith("xml:") || key.startsWith("xlink:")) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * 检查是否是特殊属性（已有专门处理逻辑的属性）
+ * 这些属性不应该进入通用属性处理流程
+ */
+export function isSpecialProperty(key: string, value: unknown): boolean {
+    return (
+        key === "ref" ||
+        key === "className" ||
+        key === "class" ||
+        key === "style" ||
+        (key.startsWith("on") && typeof value === "function") ||
+        typeof value === "boolean" ||
+        key === "value"
+    );
+}
+
+/**
+ * 智能属性设置函数
+ * HTML First 策略：优先使用 HTML 属性，避免与标准属性冲突
+ *
+ * @param element - DOM 元素
+ * @param key - 属性名
+ * @param value - 属性值
+ * @param tag - HTML 标签名（用于判断是否是 SVG）
+ */
+export function setSmartProperty(
+    element: HTMLElement | SVGElement,
+    key: string,
+    value: unknown,
+    tag: string
+): void {
+    const isSVG = shouldUseSVGNamespace(tag);
+
+    // 1. 检查是否是特殊属性（已有处理逻辑的属性）
+    if (isSpecialProperty(key, value)) {
+        return; // 由现有逻辑处理
+    }
+
+    // 2. HTML First: 优先检查是否是 HTML 标准属性
+    if (isStandardHTMLAttribute(key)) {
+        // 标准 HTML 属性：直接使用 setAttribute，不检查 JavaScript 属性
+        const attributeName = isSVG ? getSVGAttributeName(key) : key;
+
+        // 对于复杂类型，尝试序列化
+        if (typeof value === "object" && value !== null) {
+            try {
+                const serialized = JSON.stringify(value);
+                // 检查长度限制（保守估计 1MB）
+                if (serialized.length > 1024 * 1024) {
+                    logger.warn(
+                        `[WSX] Attribute "${key}" value too large, ` +
+                            `consider using a non-standard property name instead`
+                    );
+                }
+                element.setAttribute(attributeName, serialized);
+            } catch (error) {
+                // 无法序列化（如循环引用），警告并跳过
+                logger.warn(`Cannot serialize attribute "${key}":`, error);
+            }
+        } else {
+            element.setAttribute(attributeName, String(value));
+        }
+        // 重要：标准属性只使用 setAttribute，不使用 JavaScript 属性
+        return;
+    }
+
+    // 3. SVG 元素特殊处理：对于 SVG 元素，很多属性应该直接使用 setAttribute
+    // 因为 SVG 元素的很多属性是只读的（如 viewBox）
+    if (element instanceof SVGElement) {
+        const attributeName = getSVGAttributeName(key);
+        // 对于复杂类型，尝试序列化
+        if (typeof value === "object" && value !== null) {
+            try {
+                const serialized = JSON.stringify(value);
+                element.setAttribute(attributeName, serialized);
+            } catch (error) {
+                logger.warn(`Cannot serialize SVG attribute "${key}":`, error);
+            }
+        } else {
+            element.setAttribute(attributeName, String(value));
+        }
+        return;
+    }
+
+    // 4. 非标准属性：检查元素是否有该 JavaScript 属性
+    const hasProperty = key in element || Object.prototype.hasOwnProperty.call(element, key);
+
+    if (hasProperty) {
+        // 检查是否是只读属性
+        let isReadOnly = false;
+        try {
+            const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(element), key);
+            if (descriptor) {
+                isReadOnly =
+                    (descriptor.get !== undefined && descriptor.set === undefined) ||
+                    (descriptor.writable === false && descriptor.set === undefined);
+            }
+        } catch {
+            // 忽略错误，继续尝试设置
+        }
+
+        if (isReadOnly) {
+            // 只读属性使用 setAttribute
+            const attributeName = isSVG ? getSVGAttributeName(key) : key;
+            // 对于复杂类型，尝试序列化
+            if (typeof value === "object" && value !== null) {
+                try {
+                    const serialized = JSON.stringify(value);
+                    element.setAttribute(attributeName, serialized);
+                } catch (error) {
+                    logger.warn(`Cannot serialize readonly property "${key}":`, error);
+                }
+            } else {
+                element.setAttribute(attributeName, String(value));
+            }
+        } else {
+            // 使用 JavaScript 属性赋值（支持任意类型）
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (element as any)[key] = value;
+            } catch {
+                // 如果赋值失败，回退到 setAttribute
+                const attributeName = isSVG ? getSVGAttributeName(key) : key;
+                // 对于复杂类型，尝试序列化
+                if (typeof value === "object" && value !== null) {
+                    try {
+                        const serialized = JSON.stringify(value);
+                        element.setAttribute(attributeName, serialized);
+                    } catch (error) {
+                        logger.warn(
+                            `[WSX] Cannot serialize property "${key}" for attribute:`,
+                            error
+                        );
+                    }
+                } else {
+                    element.setAttribute(attributeName, String(value));
+                }
+            }
+        }
+    } else {
+        // 没有 JavaScript 属性，使用 setAttribute
+        const attributeName = isSVG ? getSVGAttributeName(key) : key;
+
+        // 对于复杂类型，尝试序列化
+        if (typeof value === "object" && value !== null) {
+            try {
+                const serialized = JSON.stringify(value);
+                // 检查长度限制
+                if (serialized.length > 1024 * 1024) {
+                    logger.warn(
+                        `[WSX] Property "${key}" value too large for attribute, ` +
+                            `consider using a JavaScript property instead`
+                    );
+                }
+                element.setAttribute(attributeName, serialized);
+            } catch (error) {
+                // 无法序列化，警告并跳过
+                logger.warn(`Cannot serialize property "${key}" for attribute:`, error);
+            }
+        } else {
+            element.setAttribute(attributeName, String(value));
+        }
+    }
+}

package/src/web-component.ts

@@ -11,6 +11,7 @@
 import { h, type JSXChildren } from "./jsx-factory";
 import { StyleManager } from "./styles/style-manager";
 import { BaseComponent, type BaseComponentConfig } from "./base-component";
+import { RenderContext } from "./render-context";
 import { createLogger } from "@wsxjs/wsx-logger";
 
 const logger = createLogger("WebComponent");
@@ -183,7 +184,7 @@ export abstract class WebComponent extends BaseComponent {
             }
 
             // 4. 重新渲染JSX
-            const content = this.render();
+            const content = RenderContext.runInContext(this, () => this.render());
 
             // 5. 在添加到 DOM 之前恢复值
             if (focusState && focusState.key && focusState.value !== undefined) {