@wsxjs/wsx-core 0.0.7 → 0.0.9

package/src/light-component.ts

@@ -8,7 +8,7 @@
  */
 
 import { h, type JSXChildren } from "./jsx-factory";
-import { reactive, createState, reactiveWithDebug } from "./utils/reactive";
+import { BaseComponent, type BaseComponentConfig } from "./base-component";
 import { createLogger } from "./utils/logger";
 
 const logger = createLogger("LightComponent");
@@ -16,35 +16,17 @@ const logger = createLogger("LightComponent");
 /**
  * Light DOM Component 配置接口
  */
-export interface LightComponentConfig {
-    styles?: string; // CSS内容
-    styleName?: string; // 样式名称，用于缓存
-    debug?: boolean; // 是否启用响应式调试模式
-    [key: string]: unknown;
-}
+export type LightComponentConfig = BaseComponentConfig;
 
 /**
  * Light DOM WSX Web Component 基类
  */
-export abstract class LightComponent extends HTMLElement {
-    protected config: LightComponentConfig;
-    protected connected: boolean = false;
-    private _isDebugEnabled: boolean = false;
-    private _reactiveStates = new Map<string, any>();
-
-    /**
-     * 子类应该重写这个方法来定义观察的属性
-     * @returns 要观察的属性名数组
-     */
-    static get observedAttributes(): string[] {
-        return [];
-    }
+export abstract class LightComponent extends BaseComponent {
+    protected config!: LightComponentConfig; // Initialized by BaseComponent constructor
 
     constructor(config: LightComponentConfig = {}) {
-        super();
-
-        this.config = config;
-        this._isDebugEnabled = config.debug ?? false;
+        super(config);
+        // BaseComponent already created this.config with getter for styles
     }
 
     /**
@@ -61,15 +43,23 @@ export abstract class LightComponent extends HTMLElement {
         this.connected = true;
         try {
             // 应用CSS样式到组件自身
-            if (this.config.styles) {
+            // CRITICAL: _defineProperty for class properties executes AFTER super() but BEFORE constructor body
+            // However, in practice, _defineProperty may execute AFTER the constructor body
+            // So we need to check _autoStyles directly first, then fallback to config.styles getter
+            // The getter will dynamically check _autoStyles when accessed
+            const stylesToApply = this._autoStyles || this.config.styles;
+            if (stylesToApply) {
                 const styleName = this.config.styleName || this.constructor.name;
-                this.applyScopedStyles(styleName, this.config.styles);
+                this.applyScopedStyles(styleName, stylesToApply);
             }
 
             // 渲染JSX内容到Light DOM
             const content = this.render();
             this.appendChild(content);
 
+            // 初始化事件监听器
+            this.initializeEventListeners();
+
             // 调用子类的初始化钩子
             this.onConnected?.();
         } catch (error) {
@@ -82,33 +72,13 @@ export abstract class LightComponent extends HTMLElement {
      * Web Component生命周期：从DOM断开
      */
     disconnectedCallback(): void {
+        this.connected = false;
+        this.cleanup(); // 清理资源（包括防抖定时器）
         this.cleanupReactiveStates();
         this.cleanupStyles();
         this.onDisconnected?.();
     }
 
-    /**
-     * Web Component生命周期：属性变化
-     */
-    attributeChangedCallback(name: string, oldValue: string, newValue: string): void {
-        this.onAttributeChanged?.(name, oldValue, newValue);
-    }
-
-    /**
-     * 可选生命周期钩子：组件已连接
-     */
-    protected onConnected?(): void;
-
-    /**
-     * 可选生命周期钩子：组件已断开
-     */
-    protected onDisconnected?(): void;
-
-    /**
-     * 可选生命周期钩子：属性已更改
-     */
-    protected onAttributeChanged?(name: string, oldValue: string, newValue: string): void;
-
     /**
      * 查找组件内的元素
      *
@@ -129,53 +99,6 @@ export abstract class LightComponent extends HTMLElement {
         return HTMLElement.prototype.querySelectorAll.call(this, selector) as NodeListOf<T>;
     }
 
-    /**
-     * 创建响应式对象
-     *
-     * @param obj 要变为响应式的对象
-     * @param debugName 调试名称（可选）
-     * @returns 响应式代理对象
-     */
-    protected reactive<T extends object>(obj: T, debugName?: string): T {
-        const reactiveFn = this._isDebugEnabled ? reactiveWithDebug : reactive;
-        const name = debugName || `${this.constructor.name}.reactive`;
-
-        return this._isDebugEnabled
-            ? reactiveFn(obj, () => this.scheduleRerender(), name)
-            : reactiveFn(obj, () => this.scheduleRerender());
-    }
-
-    /**
-     * 创建响应式状态
-     *
-     * @param key 状态标识符
-     * @param initialValue 初始值
-     * @returns [getter, setter] 元组
-     */
-    protected useState<T>(
-        key: string,
-        initialValue: T
-    ): [() => T, (value: T | ((prev: T) => T)) => void] {
-        if (!this._reactiveStates.has(key)) {
-            const [getter, setter] = createState(initialValue, () => this.scheduleRerender());
-            this._reactiveStates.set(key, { getter, setter });
-        }
-
-        const state = this._reactiveStates.get(key);
-        return [state.getter, state.setter];
-    }
-
-    /**
-     * 调度重渲染
-     * 这个方法被响应式系统调用，开发者通常不需要直接调用
-     */
-    protected scheduleRerender(): void {
-        // 确保组件已连接到 DOM
-        if (this.connected) {
-            this.rerender();
-        }
-    }
-
     /**
      * 重新渲染组件
      */
@@ -187,36 +110,97 @@ export abstract class LightComponent extends HTMLElement {
             return;
         }
 
-        // 清空现有内容（包括样式元素）
-        this.innerHTML = "";
+        // 1. 捕获焦点状态（在 DOM 替换之前）
+        const focusState = this.captureFocusState();
+        // 保存到实例变量，供 render() 使用（如果需要）
+        this._pendingFocusState = focusState;
 
-        // 重新应用样式（必须在内容之前添加，确保样式优先）
-        if (this.config.styles) {
-            const styleName = this.config.styleName || this.constructor.name;
-            // 直接创建并添加样式元素，不检查是否存在（因为 innerHTML = "" 已经清空了）
-            const styleElement = document.createElement("style");
-            styleElement.setAttribute("data-wsx-light-component", styleName);
-            styleElement.textContent = this.config.styles;
-            // 使用 prepend 或 insertBefore 确保样式在第一个位置
-            // 由于 innerHTML = "" 后 firstChild 是 null，使用 appendChild 然后调整顺序
-            this.appendChild(styleElement);
-        }
-
-        // 重新渲染JSX内容
         try {
+            // 重新渲染JSX内容
             const content = this.render();
-            this.appendChild(content);
 
-            // 确保样式元素在内容之前（如果样式存在）
-            if (this.config.styles && this.children.length > 1) {
-                const styleElement = this.querySelector(
-                    `style[data-wsx-light-component="${this.config.styleName || this.constructor.name}"]`
-                );
-                if (styleElement && styleElement !== this.firstChild) {
-                    // 将样式元素移到第一个位置
+            // 在添加到 DOM 之前恢复值，避免浏览器渲染状态值
+            // 这样可以确保值在元素添加到 DOM 之前就是正确的
+            if (focusState && focusState.key && focusState.value !== undefined) {
+                // 在 content 树中查找目标元素
+                const target = content.querySelector(
+                    `[data-wsx-key="${focusState.key}"]`
+                ) as HTMLElement;
+
+                if (target) {
+                    if (
+                        target instanceof HTMLInputElement ||
+                        target instanceof HTMLTextAreaElement
+                    ) {
+                        target.value = focusState.value;
+                    }
+                }
+            }
+
+            // 确保样式元素存在
+            const stylesToApply = this._autoStyles || this.config.styles;
+            if (stylesToApply) {
+                const styleName = this.config.styleName || this.constructor.name;
+                let styleElement = this.querySelector(
+                    `style[data-wsx-light-component="${styleName}"]`
+                ) as HTMLStyleElement;
+
+                if (!styleElement) {
+                    // 创建样式元素
+                    styleElement = document.createElement("style");
+                    styleElement.setAttribute("data-wsx-light-component", styleName);
+                    styleElement.textContent = stylesToApply;
                     this.insertBefore(styleElement, this.firstChild);
+                } else if (styleElement.textContent !== stylesToApply) {
+                    // 更新样式内容
+                    styleElement.textContent = stylesToApply;
                 }
             }
+
+            // 使用 requestAnimationFrame 批量执行 DOM 操作，减少重绘
+            // 在同一帧中完成添加和移除，避免中间状态
+            requestAnimationFrame(() => {
+                // 先添加新内容
+                this.appendChild(content);
+
+                // 立即移除旧内容（在同一帧中，浏览器会批量处理）
+                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)
+                    ) {
+                        return false;
+                    }
+                    return true;
+                });
+                oldChildren.forEach((child) => child.remove());
+
+                // 确保样式元素在第一个位置
+                if (stylesToApply && this.children.length > 1) {
+                    const styleElement = this.querySelector(
+                        `style[data-wsx-light-component="${this.config.styleName || this.constructor.name}"]`
+                    );
+                    if (styleElement && styleElement !== this.firstChild) {
+                        this.insertBefore(styleElement, this.firstChild);
+                    }
+                }
+
+                // 恢复焦点状态（在 DOM 替换之后）
+                // 值已经在添加到 DOM 之前恢复了，这里只需要恢复焦点和光标位置
+                // 使用另一个 requestAnimationFrame 确保 DOM 已完全更新
+                requestAnimationFrame(() => {
+                    this.restoreFocusState(focusState);
+                    // 清除待处理的焦点状态
+                    this._pendingFocusState = null;
+                });
+            });
         } catch (error) {
             logger.error(`[${this.constructor.name}] Error in rerender:`, error);
             this.renderError(error);
@@ -266,34 +250,6 @@ export abstract class LightComponent extends HTMLElement {
         this.insertBefore(styleElement, this.firstChild);
     }
 
-    /**
-     * 获取配置值
-     *
-     * @param key - 配置键
-     * @param defaultValue - 默认值
-     * @returns 配置值
-     */
-    protected getConfig<T>(key: string, defaultValue?: T): T {
-        return (this.config[key] as T) ?? (defaultValue as T);
-    }
-
-    /**
-     * 设置配置值
-     *
-     * @param key - 配置键
-     * @param value - 配置值
-     */
-    protected setConfig(key: string, value: unknown): void {
-        this.config[key] = value;
-    }
-
-    /**
-     * 清理响应式状态
-     */
-    private cleanupReactiveStates(): void {
-        this._reactiveStates.clear();
-    }
-
     /**
      * 清理组件样式
      */
@@ -304,46 +260,6 @@ export abstract class LightComponent extends HTMLElement {
             existingStyle.remove();
         }
     }
-
-    /**
-     * 获取属性值
-     *
-     * @param name - 属性名
-     * @param defaultValue - 默认值
-     * @returns 属性值
-     */
-    protected getAttr(name: string, defaultValue = ""): string {
-        return this.getAttribute(name) || defaultValue;
-    }
-
-    /**
-     * 设置属性值
-     *
-     * @param name - 属性名
-     * @param value - 属性值
-     */
-    protected setAttr(name: string, value: string): void {
-        this.setAttribute(name, value);
-    }
-
-    /**
-     * 移除属性
-     *
-     * @param name - 属性名
-     */
-    protected removeAttr(name: string): void {
-        this.removeAttribute(name);
-    }
-
-    /**
-     * 检查是否有属性
-     *
-     * @param name - 属性名
-     * @returns 是否存在
-     */
-    protected hasAttr(name: string): boolean {
-        return this.hasAttribute(name);
-    }
 }
 
 // 导出JSX助手

package/src/reactive-decorator.ts

@@ -0,0 +1,132 @@
+/**
+ * Reactive Decorators for WSX Components
+ *
+ * Provides @state property decorator to mark properties as reactive state.
+ * WebComponent and LightComponent already have reactive() and useState() methods.
+ * Babel plugin handles @state initialization at compile time.
+ *
+ * @example
+ * ```typescript
+ * class Counter extends WebComponent {
+ *   @state private count = 0;
+ *   @state private user = { name: "John" };
+ * }
+ * ```
+ */
+
+/**
+ * State property decorator
+ *
+ * Marks a property as reactive state. Babel plugin processes this decorator at compile time
+ * and generates initialization code in the constructor.
+ *
+ * Automatically uses reactive() for objects/arrays and useState() for primitives.
+ *
+ * @param target - The class prototype
+ * @param propertyKey - The property name
+ *
+ * @example
+ * ```typescript
+ * class MyComponent extends WebComponent {
+ *   @state private count = 0;  // Auto-initialized by Babel plugin
+ *   @state private user = { name: "John" };  // Auto-initialized by Babel plugin
+ * }
+ * ```
+ */
+export function state(target: unknown, propertyKey: string | symbol | unknown): void {
+    /**
+     * @state decorator is a compile-time marker for Babel plugin.
+     * Babel plugin will:
+     * 1. Detect @state decorator on properties
+     * 2. Extract initial value from AST
+     * 3. Remove @state decorator
+     * 4. Generate initialization code in constructor (this.state = this.reactive(...) or useState)
+     *
+     * This runtime function only performs basic validation.
+     * If Babel plugin is not configured, this will throw an error.
+     */
+
+    // Normalize propertyKey
+    let normalizedPropertyKey: string | symbol;
+    if (typeof propertyKey === "string" || typeof propertyKey === "symbol") {
+        normalizedPropertyKey = propertyKey;
+    } else {
+        const propertyKeyStr = String(propertyKey);
+        if (propertyKeyStr === "[object Object]") {
+            // Invalid propertyKey - Babel plugin was not configured
+            throw new Error(
+                `@state decorator: Invalid propertyKey detected. ` +
+                    `\n\n` +
+                    `The @state decorator MUST be processed by Babel plugin at compile time. ` +
+                    `It appears the Babel plugin is not configured in your build setup.` +
+                    `\n\n` +
+                    `To fix this, please:` +
+                    `\n1. Install @wsxjs/wsx-vite-plugin: npm install @wsxjs/wsx-vite-plugin` +
+                    `\n2. Configure it in vite.config.ts:` +
+                    `\n   import { wsx } from '@wsxjs/wsx-vite-plugin';` +
+                    `\n   export default defineConfig({ plugins: [wsx()] });` +
+                    `\n3. Configure TypeScript (recommended: use @wsxjs/wsx-tsconfig):` +
+                    `\n   npm install --save-dev @wsxjs/wsx-tsconfig` +
+                    `\n   Then in tsconfig.json: { "extends": "@wsxjs/wsx-tsconfig/tsconfig.base.json" }` +
+                    `\n   Or manually: { "compilerOptions": { "experimentalDecorators": true, "useDefineForClassFields": false } }` +
+                    `\n\n` +
+                    `See: https://github.com/wsxjs/wsxjs#setup for more details.`
+            );
+        }
+        normalizedPropertyKey = propertyKeyStr;
+    }
+
+    // Basic validation: ensure target is valid
+    if (target == null) {
+        const propertyKeyStr =
+            typeof normalizedPropertyKey === "string"
+                ? normalizedPropertyKey
+                : normalizedPropertyKey.toString();
+        throw new Error(
+            `@state decorator: Cannot access property "${propertyKeyStr}". ` +
+                `Target is ${target === null ? "null" : "undefined"}.` +
+                `\n\n` +
+                `The @state decorator MUST be processed by Babel plugin at compile time. ` +
+                `It appears the Babel plugin is not configured in your build setup.` +
+                `\n\n` +
+                `To fix this, please:` +
+                `\n1. Install @wsxjs/wsx-vite-plugin: npm install @wsxjs/wsx-vite-plugin` +
+                `\n2. Configure it in vite.config.ts:` +
+                `\n   import { wsx } from '@wsxjs/wsx-vite-plugin';` +
+                `\n   export default defineConfig({ plugins: [wsx()] });` +
+                `\n3. Configure TypeScript (recommended: use @wsxjs/wsx-tsconfig):` +
+                `\n   npm install --save-dev @wsxjs/wsx-tsconfig` +
+                `\n   Then in tsconfig.json: { "extends": "@wsxjs/wsx-tsconfig/tsconfig.base.json" }` +
+                `\n   Or manually: { "compilerOptions": { "experimentalDecorators": true, "useDefineForClassFields": false } }` +
+                `\n\n` +
+                `See: https://github.com/wsxjs/wsxjs#setup for more details.`
+        );
+    }
+
+    if (typeof target !== "object") {
+        const propertyKeyStr =
+            typeof normalizedPropertyKey === "string"
+                ? normalizedPropertyKey
+                : normalizedPropertyKey.toString();
+        throw new Error(
+            `@state decorator: Cannot be used on "${propertyKeyStr}". ` +
+                `@state is for properties only, not methods.`
+        );
+    }
+
+    // Validate that property has an initial value
+    const descriptor = Object.getOwnPropertyDescriptor(target, normalizedPropertyKey);
+    if (descriptor?.get) {
+        const propertyKeyStr =
+            typeof normalizedPropertyKey === "string"
+                ? normalizedPropertyKey
+                : normalizedPropertyKey.toString();
+        throw new Error(
+            `@state decorator cannot be used with getter properties. Property: "${propertyKeyStr}"`
+        );
+    }
+
+    // Note: We don't store metadata or remove the property here.
+    // Babel plugin handles everything at compile time.
+    // If this function is called at runtime, it means Babel plugin didn't process the decorator.
+}