@wsxjs/wsx-core 0.0.20 → 0.0.22

package/dist/index.mjs

@@ -1,7 +1,10 @@
 import {
   Fragment,
-  h
-} from "./chunk-7FXISNME.mjs";
+  RenderContext,
+  createLogger,
+  h,
+  shouldPreserveElement
+} from "./chunk-OXFZ575O.mjs";
 
 // src/styles/style-manager.ts
 var StyleManager = class {
@@ -44,8 +47,8 @@ var StyleManager = class {
 StyleManager.styleSheets = /* @__PURE__ */ new Map();
 
 // src/utils/reactive.ts
-import { createLogger } from "@wsxjs/wsx-logger";
-var logger = createLogger("ReactiveSystem");
+import { createLogger as createLogger2 } from "@wsxjs/wsx-logger";
+var logger = createLogger2("ReactiveSystem");
 var UpdateScheduler = class {
   constructor() {
     this.pendingCallbacks = /* @__PURE__ */ new Set();
@@ -264,6 +267,108 @@ function reactiveWithDebug(obj, onChange, debugName) {
   });
 }
 
+// src/dom-cache-manager.ts
+var logger2 = createLogger("DOMCacheManager");
+var DOMCacheManager = class {
+  constructor() {
+    // Map<CacheKey, DOMElement>
+    this.cache = /* @__PURE__ */ new Map();
+    // Map<DOMElement, Metadata>
+    // Stores metadata (props, children) for cached elements to support diffing
+    this.metadata = /* @__PURE__ */ new WeakMap();
+    // Track key-parent relationships to detect duplicate keys in all environments
+    // Map<CacheKey, ParentInfo>
+    this.keyParentMap = /* @__PURE__ */ new Map();
+    // Flag to enable duplicate key warnings (enabled by default, critical for correctness)
+    this.warnDuplicateKeys = true;
+  }
+  /**
+   * Retrieves an element from the cache.
+   * @param key The unique cache key.
+   */
+  get(key) {
+    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, element) {
+    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.
+   */
+  checkDuplicateKey(key, element) {
+    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 : ""}`;
+      if (currentParentInfo !== existingParentInfo) {
+        logger2.warn(
+          `Duplicate key "${key}" detected in different parent containers!
+  Previous parent: ${existingParentInfo}
+  Current parent:  ${currentParentInfo}
+
+This may cause elements to appear in wrong containers or be moved unexpectedly.
+
+Solution: Use unique key prefixes for different locations:
+  Example: <wsx-link key="nav-0"> vs <wsx-link key="overflow-0">
+
+See https://wsxjs.dev/docs/guide/DOM_CACHE_GUIDE for best practices.`
+        );
+      }
+    }
+    if (currentParent) {
+      this.keyParentMap.set(key, {
+        parentTag: currentParent.tagName.toLowerCase(),
+        parentClass: currentParent.className,
+        element
+      });
+    }
+  }
+  /**
+   * Gets a formatted parent container description.
+   */
+  getParentInfo(parent) {
+    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) {
+    return this.cache.has(key);
+  }
+  /**
+   * Clears the cache.
+   * Should be called when component is disconnected or cache is invalidated.
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Stores metadata for an element (e.g. previous props).
+   */
+  setMetadata(element, meta) {
+    this.metadata.set(element, meta);
+  }
+  /**
+   * Retrieves metadata for an element.
+   */
+  getMetadata(element) {
+    return this.metadata.get(element);
+  }
+};
+
 // src/base-component.ts
 var BaseComponent = class extends HTMLElement {
   constructor(config = {}) {
@@ -271,6 +376,11 @@ var BaseComponent = class extends HTMLElement {
     this.connected = false;
     this._isDebugEnabled = false;
     this._reactiveStates = /* @__PURE__ */ new Map();
+    /**
+     * DOM Cache Manager for fine-grained updates (RFC 0037)
+     * @internal
+     */
+    this._domCache = new DOMCacheManager();
     /**
      * 当前捕获的焦点状态（用于在 render 时使用捕获的值）
      * @internal - 由 rerender() 方法管理
@@ -335,6 +445,13 @@ var BaseComponent = class extends HTMLElement {
   static get observedAttributes() {
     return [];
   }
+  /**
+   * Gets the DOMCacheManager instance.
+   * @internal
+   */
+  getDomCache() {
+    return this._domCache;
+  }
   /**
    * Web Component生命周期：属性变化
    */
@@ -641,8 +758,8 @@ var BaseComponent = class extends HTMLElement {
 };
 
 // src/web-component.ts
-import { createLogger as createLogger2 } from "@wsxjs/wsx-logger";
-var logger2 = createLogger2("WebComponent");
+import { createLogger as createLogger3 } from "@wsxjs/wsx-logger";
+var logger3 = createLogger3("WebComponent");
 var WebComponent = class extends BaseComponent {
   // Initialized by BaseComponent constructor
   constructor(config = {}) {
@@ -680,7 +797,7 @@ var WebComponent = class extends BaseComponent {
           const styleName = this.config.styleName || this.constructor.name;
           StyleManager.applyStyles(this.shadowRoot, styleName, stylesToApply);
         }
-        const content = this.render();
+        const content = RenderContext.runInContext(this, () => this.render());
         this.shadowRoot.appendChild(content);
       }
       this.initializeEventListeners();
@@ -691,7 +808,7 @@ var WebComponent = class extends BaseComponent {
         });
       }
     } catch (error) {
-      logger2.error(`Error in connectedCallback:`, error);
+      logger3.error(`Error in connectedCallback:`, error);
       this.renderError(error);
     }
   }
@@ -744,7 +861,7 @@ var WebComponent = class extends BaseComponent {
           StyleManager.applyStyles(this.shadowRoot, styleName, stylesToApply);
         }
       }
-      const content = this.render();
+      const content = RenderContext.runInContext(this, () => this.render());
       if (focusState && focusState.key && focusState.value !== void 0) {
         const target = content.querySelector(
           `[data-wsx-key="${focusState.key}"]`
@@ -760,9 +877,18 @@ var WebComponent = class extends BaseComponent {
       }
       requestAnimationFrame(() => {
         this.shadowRoot.appendChild(content);
-        const oldChildren = Array.from(this.shadowRoot.children).filter(
-          (child) => child !== content
-        );
+        const oldChildren = Array.from(this.shadowRoot.children).filter((child) => {
+          if (child === content) {
+            return false;
+          }
+          if (child instanceof HTMLStyleElement) {
+            return false;
+          }
+          if (shouldPreserveElement(child)) {
+            return false;
+          }
+          return true;
+        });
         oldChildren.forEach((child) => child.remove());
         requestAnimationFrame(() => {
           this.restoreFocusState(focusState);
@@ -772,7 +898,7 @@ var WebComponent = class extends BaseComponent {
         });
       });
     } catch (error) {
-      logger2.error("Error in _rerender:", error);
+      logger3.error("Error in _rerender:", error);
       this.renderError(error);
       this._isRendering = false;
     }
@@ -799,8 +925,8 @@ var WebComponent = class extends BaseComponent {
 };
 
 // src/light-component.ts
-import { createLogger as createLogger3 } from "@wsxjs/wsx-logger";
-var logger3 = createLogger3("LightComponent");
+import { createLogger as createLogger4 } from "@wsxjs/wsx-logger";
+var logger4 = createLogger4("LightComponent");
 var LightComponent = class extends BaseComponent {
   // Initialized by BaseComponent constructor
   constructor(config = {}) {
@@ -842,7 +968,7 @@ var LightComponent = class extends BaseComponent {
           (child) => child !== styleElement
         );
         childrenToRemove.forEach((child) => child.remove());
-        const content = this.render();
+        const content = RenderContext.runInContext(this, () => this.render());
         this.appendChild(content);
         if (styleElement && styleElement !== this.firstChild) {
           this.insertBefore(styleElement, this.firstChild);
@@ -856,7 +982,7 @@ var LightComponent = class extends BaseComponent {
         });
       }
     } catch (error) {
-      logger3.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
+      logger4.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
       this.renderError(error);
     }
   }
@@ -904,7 +1030,7 @@ var LightComponent = class extends BaseComponent {
     this._pendingFocusState = focusState;
     const jsxChildren = this.getJSXChildren();
     try {
-      const content = this.render();
+      const content = RenderContext.runInContext(this, () => this.render());
       if (focusState && focusState.key && focusState.value !== void 0) {
         const target = content.querySelector(
           `[data-wsx-key="${focusState.key}"]`
@@ -942,6 +1068,9 @@ var LightComponent = class extends BaseComponent {
           if (child instanceof HTMLElement && jsxChildren.includes(child)) {
             return false;
           }
+          if (shouldPreserveElement(child)) {
+            return false;
+          }
           return true;
         });
         oldChildren.forEach((child) => child.remove());
@@ -961,7 +1090,7 @@ var LightComponent = class extends BaseComponent {
         });
       });
     } catch (error) {
-      logger3.error(`[${this.constructor.name}] Error in _rerender:`, error);
+      logger4.error(`[${this.constructor.name}] Error in _rerender:`, error);
       this.renderError(error);
       this._isRendering = false;
     }
@@ -1062,7 +1191,7 @@ function deriveTagName(className, prefix) {
 }
 
 // src/index.ts
-import { WSXLogger, logger as logger4, createLogger as createLogger4, createLoggerWithConfig } from "@wsxjs/wsx-logger";
+import { WSXLogger, logger as logger5, createLogger as createLogger5, createLoggerWithConfig } from "@wsxjs/wsx-logger";
 
 // src/reactive-decorator.ts
 function createBabelPluginError(propertyName) {
@@ -1083,6 +1212,10 @@ To fix this, please:
 See: https://github.com/wsxjs/wsxjs#setup for more details.`;
 }
 function state(targetOrContext, propertyKey) {
+  const globalProcess = typeof globalThis !== "undefined" ? globalThis.process : void 0;
+  if (globalProcess?.env?.NODE_ENV === "test") {
+    return;
+  }
   let propertyName = "unknown";
   const propertyKeyIsObject = typeof propertyKey === "object" && propertyKey !== null;
   const targetIsObject = typeof targetOrContext === "object" && targetOrContext !== null;
@@ -1143,12 +1276,12 @@ export {
   WSXLogger,
   WebComponent,
   autoRegister,
-  createLogger4 as createLogger,
+  createLogger5 as createLogger,
   createLoggerWithConfig,
   h,
   h as jsx,
   h as jsxs,
-  logger4 as logger,
+  logger5 as logger,
   registerComponent,
   state
 };