@wsxjs/wsx-core 0.0.19 → 0.0.21

package/dist/jsx.mjs

@@ -1,7 +1,7 @@
 import {
   Fragment,
   h
-} from "./chunk-UH5BDYGI.mjs";
+} from "./chunk-AR3DIDLV.mjs";
 export {
   Fragment,
   h

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wsxjs/wsx-core",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "description": "Core WSXJS - Web Components with JSX syntax",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -48,7 +48,7 @@
     "custom-elements"
   ],
   "dependencies": {
-    "@wsxjs/wsx-logger": "0.0.19"
+    "@wsxjs/wsx-logger": "0.0.21"
   },
   "devDependencies": {
     "tsup": "^8.0.0",

package/src/base-component.ts

@@ -9,6 +9,7 @@
  */
 
 import { reactive as createReactive, createState, reactiveWithDebug } from "./utils/reactive";
+import { DOMCacheManager } from "./dom-cache-manager";
 
 /**
  * Type for reactive state storage
@@ -60,6 +61,12 @@ export abstract class BaseComponent extends HTMLElement {
      */
     protected _autoStyles?: string;
 
+    /**
+     * DOM Cache Manager for fine-grained updates (RFC 0037)
+     * @internal
+     */
+    protected _domCache = new DOMCacheManager();
+
     /**
      * 当前捕获的焦点状态（用于在 render 时使用捕获的值）
      * @internal - 由 rerender() 方法管理
@@ -138,6 +145,14 @@ export abstract class BaseComponent extends HTMLElement {
      */
     protected onRendered?(): void;
 
+    /**
+     * Gets the DOMCacheManager instance.
+     * @internal
+     */
+    public getDomCache(): DOMCacheManager {
+        return this._domCache;
+    }
+
     /**
      * 处理 blur 事件，在用户停止输入时执行待处理的重渲染
      * @internal

package/src/dom-cache-manager.ts

@@ -0,0 +1,135 @@
+import { createLogger } from "./utils/logger";
+
+const logger = createLogger("DOMCacheManager");
+
+/**
+ * Parent container information for duplicate key detection
+ */
+interface ParentInfo {
+    parentTag: string;
+    parentClass: string;
+    element: Element;
+}
+
+/**
+ * DOMCacheManager
+ *
+ * Manages DOM element caching for fine-grained updates (RFC 0037).
+ * Stores elements by unique keys derived from component ID + position/key.
+ */
+export class DOMCacheManager {
+    // Map<CacheKey, DOMElement>
+    private cache = new Map<string, Element>();
+
+    // Map<DOMElement, Metadata>
+    // Stores metadata (props, children) for cached elements to support diffing
+    private metadata = new WeakMap<Element, Record<string, unknown>>();
+
+    // Track key-parent relationships to detect duplicate keys in all environments
+    // Map<CacheKey, ParentInfo>
+    private keyParentMap = new Map<string, ParentInfo>();
+
+    // Flag to enable duplicate key warnings (enabled by default, critical for correctness)
+    private warnDuplicateKeys = true;
+
+    /**
+     * Retrieves an element from the cache.
+     * @param key The unique cache key.
+     */
+    get(key: string): Element | undefined {
+        return this.cache.get(key);
+    }
+
+    /**
+     * Stores an element in the cache.
+     * @param key The unique cache key.
+     * @param element The DOM element to cache.
+     */
+    set(key: string, element: Element): void {
+        // Always check for duplicate keys (critical for correctness)
+        if (this.warnDuplicateKeys) {
+            this.checkDuplicateKey(key, element);
+        }
+
+        this.cache.set(key, element);
+    }
+
+    /**
+     * Checks if a cache key is being reused in a different parent container.
+     * Runs in all environments to help developers catch key conflicts early.
+     * This is critical for correctness and helps prevent subtle bugs.
+     */
+    private checkDuplicateKey(key: string, element: Element): void {
+        const existing = this.keyParentMap.get(key);
+        const currentParent = element.parentElement;
+
+        if (existing && currentParent) {
+            const currentParentInfo = this.getParentInfo(currentParent);
+            const existingParentInfo = `${existing.parentTag}${existing.parentClass ? "." + existing.parentClass : ""}`;
+
+            // Check if the element is being used in a different parent container
+            if (currentParentInfo !== existingParentInfo) {
+                logger.warn(
+                    `Duplicate key "${key}" detected in different parent containers!\n` +
+                        `  Previous parent: ${existingParentInfo}\n` +
+                        `  Current parent:  ${currentParentInfo}\n` +
+                        `\n` +
+                        `This may cause elements to appear in wrong containers or be moved unexpectedly.\n` +
+                        `\n` +
+                        `Solution: Use unique key prefixes for different locations:\n` +
+                        `  Example: <wsx-link key="nav-0"> vs <wsx-link key="overflow-0">\n` +
+                        `\n` +
+                        `See https://wsxjs.dev/docs/guide/DOM_CACHE_GUIDE for best practices.`
+                );
+            }
+        }
+
+        // Track this key-parent relationship for future checks
+        if (currentParent) {
+            this.keyParentMap.set(key, {
+                parentTag: currentParent.tagName.toLowerCase(),
+                parentClass: currentParent.className,
+                element,
+            });
+        }
+    }
+
+    /**
+     * Gets a formatted parent container description.
+     */
+    private getParentInfo(parent: Element): string {
+        const tag = parent.tagName.toLowerCase();
+        const className = parent.className;
+        return `${tag}${className ? "." + className.split(" ")[0] : ""}`;
+    }
+
+    /**
+     * Checks if a key exists in the cache.
+     */
+    has(key: string): boolean {
+        return this.cache.has(key);
+    }
+
+    /**
+     * Clears the cache.
+     * Should be called when component is disconnected or cache is invalidated.
+     */
+    clear(): void {
+        this.cache.clear();
+        // WeakMap doesn't need clearing
+    }
+
+    /**
+     * Stores metadata for an element (e.g. previous props).
+     */
+    setMetadata(element: Element, meta: Record<string, unknown>): void {
+        this.metadata.set(element, meta);
+    }
+
+    /**
+     * Retrieves metadata for an element.
+     */
+    getMetadata(element: Element): Record<string, unknown> | undefined {
+        return this.metadata.get(element);
+    }
+}

package/src/jsx-factory.ts

@@ -11,20 +11,18 @@
 
 // JSX 类型声明已移至 types/wsx-types.d.ts
 
-import { createElement, shouldUseSVGNamespace, getSVGAttributeName } from "./utils/svg-utils";
-import { parseHTMLToNodes } from "./utils/dom-utils";
-
-// JSX子元素类型
-export type JSXChildren =
-    | string
-    | number
-    | HTMLElement
-    | SVGElement
-    | DocumentFragment
-    | JSXChildren[]
-    | null
-    | undefined
-    | boolean;
+import { flattenChildren, type JSXChildren } from "./utils/dom-utils";
+import { generateCacheKey, getComponentId } from "./utils/cache-key";
+import { markElement } from "./utils/element-marking";
+import { RenderContext } from "./render-context";
+import { createElementWithPropsAndChildren } from "./utils/element-creation";
+import { updateElement } from "./utils/element-update";
+import type { BaseComponent } from "./base-component";
+import type { DOMCacheManager } from "./dom-cache-manager";
+import { createLogger } from "./utils/logger";
+const logger = createLogger("JSX Factory");
+// JSX子元素类型（从 dom-utils 重新导出以保持向后兼容）
+export type { JSXChildren } from "./utils/dom-utils";
 
 /**
  * 纯原生JSX工厂函数
@@ -44,200 +42,85 @@ export function h(
     props: Record<string, unknown> | null = {},
     ...children: JSXChildren[]
 ): HTMLElement | SVGElement {
-    // 处理组件函数
+    // 处理组件函数（不受缓存影响）
     if (typeof tag === "function") {
         return tag(props, children);
     }
 
-    // 创建DOM元素 - 自动检测SVG命名空间
-    const element = createElement(tag);
-
-    // 处理属性
-    if (props) {
-        const isSVG = shouldUseSVGNamespace(tag);
+    // 检查上下文（阶段 3.2：启用缓存机制）
+    const context = RenderContext.getCurrentComponent();
+    const cacheManager = context ? RenderContext.getDOMCache() : null;
 
-        Object.entries(props).forEach(([key, value]) => {
-            if (value === null || value === undefined || value === false) {
-                return;
-            }
-
-            // 处理ref回调
-            if (key === "ref" && typeof value === "function") {
-                value(element);
-            }
-            // 处理className和class
-            else if (key === "className" || key === "class") {
-                if (isSVG) {
-                    // SVG元素使用class属性
-                    element.setAttribute("class", value as string);
-                } else {
-                    // HTML元素可以使用className
-                    (element as HTMLElement).className = value as string;
-                }
-            }
-            // 处理style
-            else if (key === "style" && typeof value === "string") {
-                element.setAttribute("style", value);
-            }
-            // 处理事件监听器
-            else if (key.startsWith("on") && typeof value === "function") {
-                const eventName = key.slice(2).toLowerCase();
-                element.addEventListener(eventName, value as EventListener);
-            }
-            // 处理布尔属性
-            else if (typeof value === "boolean") {
-                if (value) {
-                    element.setAttribute(key, "");
-                }
-            }
-            // 特殊处理 input/textarea/select 的 value 属性
-            // 使用 .value 而不是 setAttribute，因为 .value 是当前值，setAttribute 是初始值
-            else if (key === "value") {
-                if (
-                    element instanceof HTMLInputElement ||
-                    element instanceof HTMLTextAreaElement ||
-                    element instanceof HTMLSelectElement
-                ) {
-                    element.value = String(value);
-                } else {
-                    // 对于其他元素，使用 setAttribute
-                    const attributeName = isSVG ? getSVGAttributeName(key) : key;
-                    element.setAttribute(attributeName, String(value));
-                }
-            }
-            // 处理其他属性
-            else {
-                // 对SVG元素使用正确的属性名
-                const attributeName = isSVG ? getSVGAttributeName(key) : key;
-                element.setAttribute(attributeName, String(value));
-            }
-        });
+    if (context && cacheManager) {
+        return tryUseCacheOrCreate(tag, props, children, context, cacheManager);
     }
 
-    // 处理子元素
-    const flatChildren = flattenChildren(children);
-    flatChildren.forEach((child) => {
-        if (child === null || child === undefined || child === false) {
-            return;
-        }
-
-        if (typeof child === "string" || typeof child === "number") {
-            element.appendChild(document.createTextNode(String(child)));
-        } else if (child instanceof HTMLElement || child instanceof SVGElement) {
-            element.appendChild(child);
-        } else if (child instanceof DocumentFragment) {
-            element.appendChild(child);
-        }
-    });
-
-    return element;
+    // 无上下文：使用旧逻辑（向后兼容）
+    return createElementWithPropsAndChildren(tag, props, children);
 }
 
 /**
- * 检测字符串是否包含HTML标签
- * 使用更严格的检测：必须包含完整的 HTML 标签（开始和结束标签，或自闭合标签）
+ * Tries to use cached element or creates a new one.
  */
-function isHTMLString(str: string): boolean {
-    const trimmed = str.trim();
-    if (!trimmed) return false;
-
-    // 更严格的检测：必须包含完整的 HTML 标签
-    // 1. 必须以 < 开头
-    // 2. 后面跟着字母（标签名）
-    // 3. 必须包含 > 来闭合标签
-    // 4. 排除单独的 < 或 > 符号（如数学表达式 "a < b"）
-    const htmlTagPattern = /<[a-z][a-z0-9]*(\s[^>]*)?(\/>|>)/i;
-
-    // 额外检查：确保不是纯文本中的 < 和 >（如 "a < b" 或 "x > y"）
-    // 如果字符串看起来像数学表达式或纯文本，不应该被检测为 HTML
-    const looksLikeMath = /^[^<]*<[^>]*>[^>]*$/.test(trimmed) && !htmlTagPattern.test(trimmed);
-    if (looksLikeMath) return false;
+function tryUseCacheOrCreate(
+    tag: string,
+    props: Record<string, unknown> | null,
+    children: JSXChildren[],
+    context: BaseComponent,
+    cacheManager: DOMCacheManager
+): HTMLElement | SVGElement {
+    try {
+        const componentId = getComponentId();
+        const cacheKey = generateCacheKey(tag, props, componentId, context);
+        const cachedElement = cacheManager.get(cacheKey);
+
+        if (cachedElement) {
+            // ✅ 缓存命中：复用元素并更新内容（阶段 4：细粒度更新）
+            // 缓存键已经确保了唯一性（componentId + tag + position/key/index）
+            // 不需要再检查标签名（可能导致错误复用）
+            const element = cachedElement as HTMLElement | SVGElement;
+            updateElement(element, props, children, tag, cacheManager);
+            return element;
+        }
 
-    return htmlTagPattern.test(trimmed);
+        // ❌ 缓存未命中：创建新元素
+        const element = createElementWithPropsAndChildren(tag, props, children);
+        cacheManager.set(cacheKey, element);
+        markElement(element, cacheKey);
+        // 保存初始元数据（用于下次更新）
+        cacheManager.setMetadata(element, {
+            props: props || {},
+            children: children,
+        });
+        return element;
+    } catch (error) {
+        // 缓存失败：降级到创建新元素
+        return handleCacheError(error, tag, props, children);
+    }
 }
 
 /**
- * 扁平化子元素数组
- * 自动检测HTML字符串并转换为DOM节点
- *
- * @param children - 子元素数组
- * @param skipHTMLDetection - 是否跳过HTML检测（用于已解析的节点，避免无限递归）
- * @param depth - 当前递归深度（防止无限递归，最大深度为 10）
+ * Handles cache errors by logging and falling back to creating a new element.
  */
-function flattenChildren(
-    children: JSXChildren[],
-    skipHTMLDetection: boolean = false,
-    depth: number = 0
-): (string | number | HTMLElement | SVGElement | DocumentFragment | boolean | null | undefined)[] {
-    // 防止无限递归：如果深度超过 10，停止处理
-    if (depth > 10) {
-        console.warn(
-            "[WSX] flattenChildren: Maximum depth exceeded, treating remaining children as text"
-        );
-        return children.filter(
-            (child): child is string | number =>
-                typeof child === "string" || typeof child === "number"
-        );
-    }
-    const result: (
-        | string
-        | number
-        | HTMLElement
-        | SVGElement
-        | DocumentFragment
-        | boolean
-        | null
-        | undefined
-    )[] = [];
-
-    for (const child of children) {
-        if (child === null || child === undefined || child === false) {
-            continue;
-        } else if (Array.isArray(child)) {
-            // 递归处理数组，保持 skipHTMLDetection 状态，增加深度
-            result.push(...flattenChildren(child, skipHTMLDetection, depth + 1));
-        } else if (typeof child === "string") {
-            // 如果跳过HTML检测，直接添加字符串（避免无限递归）
-            if (skipHTMLDetection) {
-                result.push(child);
-            } else if (isHTMLString(child)) {
-                // 自动检测HTML字符串并转换为DOM节点
-                // 使用 try-catch 防止解析失败导致崩溃
-                try {
-                    const nodes = parseHTMLToNodes(child);
-                    // 递归处理转换后的节点数组，标记为已解析，避免再次检测HTML
-                    // parseHTMLToNodes 返回的字符串是纯文本节点，不应该再次被检测为HTML
-                    // 但是为了安全，我们仍然设置 skipHTMLDetection = true
-                    if (nodes.length > 0) {
-                        // 直接添加解析后的节点，不再递归处理（避免无限递归）
-                        // parseHTMLToNodes 已经完成了所有解析工作
-                        for (const node of nodes) {
-                            if (typeof node === "string") {
-                                // 文本节点直接添加，不再检测 HTML（已解析）
-                                result.push(node);
-                            } else {
-                                // DOM 元素直接添加
-                                result.push(node);
-                            }
-                        }
-                    } else {
-                        // 如果解析失败，回退到纯文本
-                        result.push(child);
-                    }
-                } catch (error) {
-                    // 如果解析失败，回退到纯文本，避免崩溃
-                    console.warn("[WSX] Failed to parse HTML string, treating as text:", error);
-                    result.push(child);
-                }
-            } else {
-                result.push(child);
-            }
-        } else {
-            result.push(child);
+function handleCacheError(
+    error: unknown,
+    tag: string,
+    props: Record<string, unknown> | null,
+    children: JSXChildren[]
+): HTMLElement | SVGElement {
+    // 在开发环境输出警告，帮助调试
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const nodeEnv = (typeof (globalThis as any).process !== "undefined" &&
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (globalThis as any).process.env?.NODE_ENV) as string | undefined;
+        if (nodeEnv === "development") {
+            logger.warn("[WSX DOM Cache] Cache error, falling back to create new element:", error);
         }
+    } catch {
+        // 忽略环境变量检查错误
     }
-
-    return result;
+    return createElementWithPropsAndChildren(tag, props, children);
 }
 
 /**

package/src/light-component.ts

@@ -9,6 +9,7 @@
 
 import { h, type JSXChildren } from "./jsx-factory";
 import { BaseComponent, type BaseComponentConfig } from "./base-component";
+import { RenderContext } from "./render-context";
 import { createLogger } from "@wsxjs/wsx-logger";
 
 const logger = createLogger("LightComponent");
@@ -95,7 +96,7 @@ export abstract class LightComponent extends BaseComponent {
                 childrenToRemove.forEach((child) => child.remove());
 
                 // 渲染JSX内容到Light DOM
-                const content = this.render();
+                const content = RenderContext.runInContext(this, () => this.render());
                 this.appendChild(content);
 
                 // 确保样式元素在第一个位置（如果存在）
@@ -178,7 +179,7 @@ export abstract class LightComponent extends BaseComponent {
 
         try {
             // 3. 重新渲染JSX内容
-            const content = this.render();
+            const content = RenderContext.runInContext(this, () => this.render());
 
             // 4. 在添加到 DOM 之前恢复值，避免浏览器渲染状态值
             if (focusState && focusState.key && focusState.value !== undefined) {

package/src/reactive-decorator.ts

@@ -78,6 +78,15 @@ export function state(
     // Compatibility with Babel plugin which is required for this decorator to work properly
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): any {
+    // RFC 0037 Phase 0: Test Infrastructure Support
+    // Allow runtime decorator in tests to bypass Babel plugin requirement
+    // Use globalThis to safely access process in all environments
+
+    const globalProcess =
+        typeof globalThis !== "undefined" ? (globalThis as any).process : undefined;
+    if (globalProcess?.env?.NODE_ENV === "test") {
+        return;
+    }
     /**
      * @state decorator MUST be processed by Babel plugin at compile time.
      * If this function is executed at runtime, it means Babel plugin did not process it.

package/src/render-context.ts

@@ -0,0 +1,40 @@
+import { BaseComponent } from "./base-component";
+
+/**
+ * RenderContext
+ *
+ * Tracks the currently rendering component instance.
+ * improved for RFC 0037 to support DOM caching and optimization.
+ */
+export class RenderContext {
+    private static current: BaseComponent | null = null;
+
+    /**
+     * Executes a function within the context of a component.
+     * @param component The component instance currently rendering.
+     * @param fn The function to execute (usually the render method).
+     */
+    static runInContext<T>(component: BaseComponent, fn: () => T): T {
+        const prev = RenderContext.current;
+        RenderContext.current = component;
+        try {
+            return fn();
+        } finally {
+            RenderContext.current = prev;
+        }
+    }
+
+    /**
+     * Gets the currently rendering component.
+     */
+    static getCurrentComponent(): BaseComponent | null {
+        return RenderContext.current;
+    }
+
+    /**
+     * Gets the current component's DOM cache.
+     */
+    static getDOMCache() {
+        return RenderContext.current?.getDomCache();
+    }
+}