@wsxjs/wsx-core 0.0.20 → 0.0.21

package/dist/jsx.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wsxjs/wsx-core",
-  "version": "0.0.20",
+  "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.20"
+    "@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);
+    }
+}