@wsxjs/wsx-core 0.0.17 → 0.0.18

package/src/base-component.ts

@@ -78,6 +78,12 @@ export abstract class BaseComponent extends HTMLElement {
      */
     private _pendingRerender: boolean = false;
 
+    /**
+     * 正在渲染标志（防止在 _rerender() 执行期间再次触发 scheduleRerender()）
+     * @internal
+     */
+    protected _isRendering: boolean = false;
+
     /**
      * 子类应该重写这个方法来定义观察的属性
      * @returns 要观察的属性名数组
@@ -126,6 +132,12 @@ export abstract class BaseComponent extends HTMLElement {
      */
     protected onConnected?(): void;
 
+    /**
+     * 可选生命周期钩子：组件渲染完成后调用
+     * 在 DOM 更新完成后调用，适合执行需要访问 DOM 的操作（如语法高亮、初始化第三方库等）
+     */
+    protected onRendered?(): void;
+
     /**
      * 处理 blur 事件，在用户停止输入时执行待处理的重渲染
      * @internal
@@ -146,9 +158,14 @@ export abstract class BaseComponent extends HTMLElement {
 
                 // 延迟一小段时间后重渲染，确保 blur 事件完全处理
                 requestAnimationFrame(() => {
-                    if (this._pendingRerender && this.connected) {
+                    if (this._pendingRerender && this.connected && !this._isRendering) {
                         this._pendingRerender = false;
-                        this.rerender();
+                        // 设置渲染标志，防止在 _rerender() 执行期间再次触发
+                        // 注意：_isRendering 标志会在 _rerender() 的 onRendered() 调用完成后清除
+                        this._isRendering = true;
+                        // 调用 _rerender() 执行实际渲染（不再调用 rerender()，避免循环）
+                        // _isRendering 标志会在 _rerender() 完成所有异步操作后清除
+                        this._rerender();
                     }
                 });
             }
@@ -229,6 +246,11 @@ export abstract class BaseComponent extends HTMLElement {
             return;
         }
 
+        // 如果正在渲染，跳过本次调度（防止无限循环）
+        if (this._isRendering) {
+            return;
+        }
+
         // 检查是否有需要持续输入的元素获得焦点（input、textarea、select、contenteditable）
         // 按钮等其他元素应该立即重渲染，以反映状态变化
         const root = this.getActiveRoot();
@@ -273,18 +295,50 @@ export abstract class BaseComponent extends HTMLElement {
             // 对于按钮等其他元素，或者有 data-wsx-force-render 属性的输入元素，继续执行重渲染（不跳过）
         }
 
-        // 没有焦点元素，立即重渲染（使用 queueMicrotask 批量处理）
+        // 没有焦点元素，立即重渲染（使用 requestAnimationFrame 确保在下一个渲染帧执行）
         // 如果有待处理的重渲染，也立即执行
         if (this._pendingRerender) {
             this._pendingRerender = false;
         }
-        queueMicrotask(() => {
-            if (this.connected) {
-                this.rerender();
+        // 使用 requestAnimationFrame 而不是 queueMicrotask，确保在渲染帧中执行
+        // 这样可以避免在 render() 执行期间触发的 scheduleRerender() 立即执行
+        requestAnimationFrame(() => {
+            if (this.connected && !this._isRendering) {
+                // 设置渲染标志，防止在 _rerender() 执行期间再次触发
+                // 注意：_isRendering 标志会在 _rerender() 的 onRendered() 调用完成后清除
+                this._isRendering = true;
+                // 调用 _rerender() 执行实际渲染（不再调用 rerender()，避免循环）
+                // _isRendering 标志会在 _rerender() 完成所有异步操作后清除
+                this._rerender();
+            } else if (!this.connected) {
+                // 如果组件已断开，确保清除渲染标志
+                this._isRendering = false;
             }
         });
     }
 
+    /**
+     * 调度重渲染（公开 API）
+     *
+     * 与 scheduleRerender() 对齐：所有重渲染都通过统一的调度机制
+     * 使用异步调度机制，自动处理防抖和批量更新
+     *
+     * 注意：此方法现在是异步的，使用调度机制
+     * 如果需要同步执行，使用 _rerender()（不推荐，仅内部使用）
+     */
+    protected rerender(): void {
+        // 对齐到 scheduleRerender()，统一调度机制
+        this.scheduleRerender();
+    }
+
+    /**
+     * 内部重渲染实现（同步执行）
+     * 由 scheduleRerender() 在适当时机调用
+     *
+     * @internal - 子类需要实现此方法
+     */
+    protected abstract _rerender(): void;
+
     /**
      * 清理资源（在组件断开连接时调用）
      * @internal
@@ -312,11 +366,6 @@ export abstract class BaseComponent extends HTMLElement {
         document.addEventListener("blur", this.handleGlobalBlur, true);
     }
 
-    /**
-     * 重新渲染组件（子类需要实现）
-     */
-    protected abstract rerender(): void;
-
     /**
      * 获取配置值
      *

package/src/index.ts

@@ -4,7 +4,9 @@ export { LightComponent } from "./light-component";
 export { autoRegister, registerComponent } from "./auto-register";
 export { h, h as jsx, h as jsxs, Fragment } from "./jsx-factory";
 export { StyleManager } from "./styles/style-manager";
-export { WSXLogger, logger, createLogger } from "./utils/logger";
+// Re-export logger from wsx-logger for backward compatibility
+export { WSXLogger, logger, createLogger, createLoggerWithConfig } from "@wsxjs/wsx-logger";
+export type { Logger, LogLevel } from "@wsxjs/wsx-logger";
 
 // Reactive exports - Decorator-based API
 export { state } from "./reactive-decorator";
@@ -13,5 +15,4 @@ export { state } from "./reactive-decorator";
 export type { WebComponentConfig } from "./web-component";
 export type { LightComponentConfig } from "./light-component";
 export type { JSXChildren } from "./jsx-factory";
-export type { Logger, LogLevel } from "./utils/logger";
 export type { ReactiveCallback } from "./utils/reactive";

package/src/jsx-factory.ts

@@ -12,6 +12,7 @@
 // JSX 类型声明已移至 types/wsx-types.d.ts
 
 import { createElement, shouldUseSVGNamespace, getSVGAttributeName } from "./utils/svg-utils";
+import { parseHTMLToNodes } from "./utils/dom-utils";
 
 // JSX子元素类型
 export type JSXChildren =
@@ -132,12 +133,52 @@ export function h(
     return element;
 }
 
+/**
+ * 检测字符串是否包含HTML标签
+ * 使用更严格的检测：必须包含完整的 HTML 标签（开始和结束标签，或自闭合标签）
+ */
+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;
+
+    return htmlTagPattern.test(trimmed);
+}
+
 /**
  * 扁平化子元素数组
+ * 自动检测HTML字符串并转换为DOM节点
+ *
+ * @param children - 子元素数组
+ * @param skipHTMLDetection - 是否跳过HTML检测（用于已解析的节点，避免无限递归）
+ * @param depth - 当前递归深度（防止无限递归，最大深度为 10）
  */
 function flattenChildren(
-    children: JSXChildren[]
+    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
@@ -153,7 +194,44 @@ function flattenChildren(
         if (child === null || child === undefined || child === false) {
             continue;
         } else if (Array.isArray(child)) {
-            result.push(...flattenChildren(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);
         }

package/src/light-component.ts

@@ -9,7 +9,7 @@
 
 import { h, type JSXChildren } from "./jsx-factory";
 import { BaseComponent, type BaseComponentConfig } from "./base-component";
-import { createLogger } from "./utils/logger";
+import { createLogger } from "@wsxjs/wsx-logger";
 
 const logger = createLogger("LightComponent");
 
@@ -59,8 +59,9 @@ export abstract class LightComponent extends BaseComponent {
                 this.applyScopedStyles(styleName, stylesToApply);
             }
 
-            // 检查是否有实际内容（排除样式元素）
+            // 检查是否有实际内容（排除样式元素和 slot 元素）
             // 错误元素：如果存在错误信息，需要重新渲染以恢复正常
+            // Slot 元素：不算"内容"，因为 slot 的内容在 Light DOM 中（通过 JSX children 传递）
             const styleElement = this.querySelector(
                 `style[data-wsx-light-component="${styleName}"]`
             ) as HTMLStyleElement | null;
@@ -71,14 +72,16 @@ export abstract class LightComponent extends BaseComponent {
                     child.style.color === "red" &&
                     child.textContent?.includes("Component Error")
             );
+            // 排除样式元素和 slot 元素
             const hasActualContent = Array.from(this.children).some(
-                (child) => child !== styleElement
+                (child) => child !== styleElement && !(child instanceof HTMLSlotElement)
             );
 
             // 如果有错误元素，需要重新渲染以恢复正常
             // 如果有实际内容且没有错误，跳过渲染（避免重复元素）
             if (hasActualContent && !hasErrorElement) {
-                // 已经有内容且没有错误，跳过渲染（避免重复元素）
+                // 已经有内容（JSX children），标记它们
+                this.markJSXChildren(); // 标记 JSX children，以便在 _rerender() 中保留
                 // 但确保样式元素在正确位置
                 if (styleElement && styleElement !== this.firstChild) {
                     this.insertBefore(styleElement, this.firstChild);
@@ -106,6 +109,14 @@ export abstract class LightComponent extends BaseComponent {
 
             // 调用子类的初始化钩子（无论是否渲染，都需要调用，因为组件已连接）
             this.onConnected?.();
+
+            // 如果进行了渲染，调用 onRendered 钩子
+            if (hasActualContent === false || hasErrorElement) {
+                // 使用 requestAnimationFrame 确保 DOM 已完全更新
+                requestAnimationFrame(() => {
+                    this.onRendered?.();
+                });
+            }
         } catch (error) {
             logger.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
             this.renderError(error);
@@ -144,29 +155,33 @@ export abstract class LightComponent extends BaseComponent {
     }
 
     /**
-     * 重新渲染组件
+     * 内部重渲染实现
+     * 包含从 rerender() 方法迁移的实际渲染逻辑
+     * 处理 JSX children 的保留（Light DOM 特有）
+     *
+     * @override
      */
-    protected rerender(): void {
+    protected _rerender(): void {
         if (!this.connected) {
-            logger.warn(
-                `[${this.constructor.name}] Component is not connected, skipping rerender.`
-            );
+            // 如果组件未连接，清除渲染标志
+            this._isRendering = false;
             return;
         }
 
         // 1. 捕获焦点状态（在 DOM 替换之前）
         const focusState = this.captureFocusState();
-        // 保存到实例变量，供 render() 使用（如果需要）
         this._pendingFocusState = focusState;
 
+        // 2. 保存 JSX children（通过 JSX factory 直接添加的 children）
+        // 这些 children 不是 render() 返回的内容，应该保留
+        const jsxChildren = this.getJSXChildren();
+
         try {
-            // 重新渲染JSX内容
+            // 3. 重新渲染JSX内容
             const content = this.render();
 
-            // 在添加到 DOM 之前恢复值，避免浏览器渲染状态值
-            // 这样可以确保值在元素添加到 DOM 之前就是正确的
+            // 4. 在添加到 DOM 之前恢复值，避免浏览器渲染状态值
             if (focusState && focusState.key && focusState.value !== undefined) {
-                // 在 content 树中查找目标元素
                 const target = content.querySelector(
                     `[data-wsx-key="${focusState.key}"]`
                 ) as HTMLElement;
@@ -181,10 +196,10 @@ export abstract class LightComponent extends BaseComponent {
                 }
             }
 
-            // 确保样式元素存在
+            // 5. 确保样式元素存在
             const stylesToApply = this._autoStyles || this.config.styles;
+            const styleName = this.config.styleName || this.constructor.name;
             if (stylesToApply) {
-                const styleName = this.config.styleName || this.constructor.name;
                 let styleElement = this.querySelector(
                     `style[data-wsx-light-component="${styleName}"]`
                 ) as HTMLStyleElement;
@@ -201,27 +216,29 @@ export abstract class LightComponent extends BaseComponent {
                 }
             }
 
-            // 使用 requestAnimationFrame 批量执行 DOM 操作，减少重绘
-            // 在同一帧中完成添加和移除，避免中间状态
+            // 6. 使用 requestAnimationFrame 批量执行 DOM 操作
             requestAnimationFrame(() => {
                 // 先添加新内容
                 this.appendChild(content);
 
-                // 立即移除旧内容（在同一帧中，浏览器会批量处理）
+                // 移除旧内容（保留 JSX children 和样式元素）
                 const oldChildren = Array.from(this.children).filter((child) => {
                     // 保留新添加的内容
                     if (child === content) {
                         return false;
                     }
-                    // 保留样式元素（如果存在）
+                    // 保留样式元素
                     if (
                         stylesToApply &&
                         child instanceof HTMLStyleElement &&
-                        child.getAttribute("data-wsx-light-component") ===
-                            (this.config.styleName || this.constructor.name)
+                        child.getAttribute("data-wsx-light-component") === styleName
                     ) {
                         return false;
                     }
+                    // 保留 JSX children（关键修复）
+                    if (child instanceof HTMLElement && jsxChildren.includes(child)) {
+                        return false;
+                    }
                     return true;
                 });
                 oldChildren.forEach((child) => child.remove());
@@ -229,28 +246,74 @@ export abstract class LightComponent extends BaseComponent {
                 // 确保样式元素在第一个位置
                 if (stylesToApply && this.children.length > 1) {
                     const styleElement = this.querySelector(
-                        `style[data-wsx-light-component="${this.config.styleName || this.constructor.name}"]`
+                        `style[data-wsx-light-component="${styleName}"]`
                     );
                     if (styleElement && styleElement !== this.firstChild) {
                         this.insertBefore(styleElement, this.firstChild);
                     }
                 }
 
-                // 恢复焦点状态（在 DOM 替换之后）
-                // 值已经在添加到 DOM 之前恢复了，这里只需要恢复焦点和光标位置
-                // 使用另一个 requestAnimationFrame 确保 DOM 已完全更新
+                // 恢复焦点状态
                 requestAnimationFrame(() => {
                     this.restoreFocusState(focusState);
-                    // 清除待处理的焦点状态
                     this._pendingFocusState = null;
+                    // 调用 onRendered 生命周期钩子
+                    this.onRendered?.();
+                    // 在 onRendered() 完成后清除渲染标志，允许后续的 scheduleRerender()
+                    this._isRendering = false;
                 });
             });
         } catch (error) {
-            logger.error(`[${this.constructor.name}] Error in rerender:`, error);
+            logger.error(`[${this.constructor.name}] Error in _rerender:`, error);
             this.renderError(error);
+            // 即使出错也要清除渲染标志，允许后续的 scheduleRerender()
+            this._isRendering = false;
         }
     }
 
+    /**
+     * 获取 JSX children（通过 JSX factory 直接添加的 children）
+     *
+     * 在 Light DOM 中，JSX children 是通过 JSX factory 直接添加到组件元素的
+     * 这些 children 不是 render() 返回的内容，应该保留
+     */
+    private getJSXChildren(): HTMLElement[] {
+        // 在 connectedCallback 中标记的 JSX children
+        // 使用 data 属性标记：data-wsx-jsx-child="true"
+        const jsxChildren = Array.from(this.children)
+            .filter(
+                (child) =>
+                    child instanceof HTMLElement &&
+                    child.getAttribute("data-wsx-jsx-child") === "true"
+            )
+            .map((child) => child as HTMLElement);
+
+        return jsxChildren;
+    }
+
+    /**
+     * 标记 JSX children（在 connectedCallback 中调用）
+     */
+    private markJSXChildren(): void {
+        // 在 connectedCallback 中，如果 hasActualContent 为 true
+        // 说明这些 children 是 JSX children，不是 render() 返回的内容
+        // 标记它们，以便在 _rerender() 中保留
+        const styleName = this.config.styleName || this.constructor.name;
+        const styleElement = this.querySelector(
+            `style[data-wsx-light-component="${styleName}"]`
+        ) as HTMLStyleElement | null;
+
+        Array.from(this.children).forEach((child) => {
+            if (
+                child instanceof HTMLElement &&
+                child !== styleElement &&
+                !(child instanceof HTMLSlotElement)
+            ) {
+                child.setAttribute("data-wsx-jsx-child", "true");
+            }
+        });
+    }
+
     /**
      * 渲染错误信息
      *
@@ -258,6 +321,8 @@ export abstract class LightComponent extends BaseComponent {
      */
     private renderError(error: unknown): void {
         // 清空现有内容
+        // Note: innerHTML is used here for framework-level error handling
+        // This is an exception to the no-inner-html rule for framework code
         this.innerHTML = "";
 
         const errorElement = h(

package/src/utils/dom-utils.ts

@@ -0,0 +1,48 @@
+/**
+ * DOM utilities for WSX
+ *
+ * Provides helper functions for DOM manipulation and HTML parsing
+ */
+
+/**
+ * Convert HTML string to DOM nodes (elements and text)
+ *
+ * This function parses an HTML string and returns an array of DOM nodes
+ * that can be used directly in WSX JSX. Text nodes are converted to strings,
+ * while HTML/SVG elements are kept as DOM elements.
+ *
+ * @param html - HTML string to parse
+ * @returns Array of HTMLElement, SVGElement, or string (for text nodes)
+ *
+ * @example
+ * ```tsx
+ * const nodes = parseHTMLToNodes('<p>Hello <strong>World</strong></p>');
+ * // Returns: [HTMLElement (<p>), ...]
+ *
+ * return (
+ *   <div>
+ *     {nodes}
+ *   </div>
+ * );
+ * ```
+ */
+export function parseHTMLToNodes(html: string): (HTMLElement | SVGElement | string)[] {
+    if (!html) return [];
+
+    // Create a temporary container to parse HTML
+    // Note: innerHTML is used here for framework-level HTML parsing utility
+    // This is an exception to the no-inner-html rule for framework code
+    const temp = document.createElement("div");
+    temp.innerHTML = html;
+
+    // Convert all child nodes to array
+    // Text nodes are converted to strings, elements are kept as-is
+    return Array.from(temp.childNodes).map((node) => {
+        if (node instanceof HTMLElement || node instanceof SVGElement) {
+            return node;
+        } else {
+            // Convert text nodes and other node types to strings
+            return node.textContent || "";
+        }
+    });
+}

package/src/utils/logger.ts

@@ -1,7 +1,7 @@
 /**
- * WSX Framework Logger
+ * WSXJS Logger
  *
- * A lightweight logging utility for the WSX framework.
+ * A lightweight logging utility for the WSXJS.
  * Can be extended or replaced by consuming applications.
  */
 

package/src/utils/reactive.ts

@@ -4,7 +4,7 @@
  * 基于浏览器原生 Proxy API 实现轻量级响应式状态，
  * 遵循 WSX 设计哲学：信任浏览器，零运行时开销
  */
-import { createLogger } from "./logger";
+import { createLogger } from "@wsxjs/wsx-logger";
 
 const logger = createLogger("ReactiveSystem");