@wsxjs/wsx-core 0.0.5

package/src/utils/reactive.ts

@@ -0,0 +1,214 @@
+/**
+ * WSX 响应式状态系统
+ *
+ * 基于浏览器原生 Proxy API 实现轻量级响应式状态，
+ * 遵循 WSX 设计哲学：信任浏览器，零运行时开销
+ */
+import { createLogger } from "./logger";
+
+const logger = createLogger("ReactiveSystem");
+
+/**
+ * 响应式回调函数类型
+ */
+export type ReactiveCallback = () => void;
+
+/**
+ * 批量更新调度器
+ * 使用浏览器原生的 queueMicrotask 实现批量更新
+ */
+class UpdateScheduler {
+    private pendingCallbacks = new Set<ReactiveCallback>();
+    private isScheduled = false;
+
+    /**
+     * 调度一个更新回调
+     */
+    schedule(callback: ReactiveCallback): void {
+        this.pendingCallbacks.add(callback);
+
+        if (!this.isScheduled) {
+            this.isScheduled = true;
+            // 使用浏览器原生的微任务队列
+            queueMicrotask(() => {
+                this.flush();
+            });
+        }
+    }
+
+    /**
+     * 执行所有待处理的回调
+     */
+    private flush(): void {
+        const callbacks = Array.from(this.pendingCallbacks);
+        this.pendingCallbacks.clear();
+        this.isScheduled = false;
+
+        // 执行所有回调
+        callbacks.forEach((callback) => {
+            try {
+                callback();
+            } catch (error) {
+                console.error("[WSX Reactive] Error in callback:", error);
+            }
+        });
+    }
+}
+
+// 全局调度器实例
+const scheduler = new UpdateScheduler();
+
+/**
+ * 创建响应式对象
+ *
+ * @param obj 要变为响应式的对象
+ * @param onChange 状态变化时的回调函数
+ * @returns 响应式代理对象
+ */
+export function reactive<T extends object>(obj: T, onChange: ReactiveCallback): T {
+    return new Proxy(obj, {
+        set(target: T, key: string | symbol, value: any): boolean {
+            const oldValue = target[key as keyof T];
+
+            // 只有值真正改变时才触发更新
+            if (oldValue !== value) {
+                target[key as keyof T] = value;
+
+                // 调度更新
+                scheduler.schedule(onChange);
+            }
+
+            return true;
+        },
+
+        get(target: T, key: string | symbol): any {
+            return target[key as keyof T];
+        },
+
+        has(target: T, key: string | symbol): boolean {
+            return key in target;
+        },
+
+        ownKeys(target: T): ArrayLike<string | symbol> {
+            return Reflect.ownKeys(target);
+        },
+
+        getOwnPropertyDescriptor(target: T, key: string | symbol): PropertyDescriptor | undefined {
+            return Reflect.getOwnPropertyDescriptor(target, key);
+        },
+    });
+}
+
+/**
+ * 创建响应式状态钩子
+ * 提供类似 useState 的 API
+ *
+ * @param initialValue 初始值
+ * @param onChange 变化回调
+ * @returns [getter, setter] 元组
+ */
+export function createState<T>(
+    initialValue: T,
+    onChange: ReactiveCallback
+): [() => T, (value: T | ((prev: T) => T)) => void] {
+    let currentValue = initialValue;
+
+    const getter = (): T => currentValue;
+
+    const setter = (value: T | ((prev: T) => T)): void => {
+        const newValue =
+            typeof value === "function" ? (value as (prev: T) => T)(currentValue) : value;
+
+        if (currentValue !== newValue) {
+            currentValue = newValue;
+            scheduler.schedule(onChange);
+        }
+    };
+
+    return [getter, setter];
+}
+
+/**
+ * 检查一个值是否为响应式对象
+ */
+export function isReactive(value: any): boolean {
+    return (
+        value != null &&
+        typeof value === "object" &&
+        value.constructor === Object &&
+        typeof value.valueOf === "function"
+    );
+}
+
+/**
+ * 开发模式下的调试工具
+ */
+export const ReactiveDebug = {
+    /**
+     * 启用调试模式
+     */
+    enable(): void {
+        if (typeof window !== "undefined") {
+            (window as any).__WSX_REACTIVE_DEBUG__ = true;
+        }
+    },
+
+    /**
+     * 禁用调试模式
+     */
+    disable(): void {
+        if (typeof window !== "undefined") {
+            (window as any).__WSX_REACTIVE_DEBUG__ = false;
+        }
+    },
+
+    /**
+     * 检查是否启用调试模式
+     */
+    isEnabled(): boolean {
+        return typeof window !== "undefined" && (window as any).__WSX_REACTIVE_DEBUG__ === true;
+    },
+
+    /**
+     * 调试日志
+     */
+    log(message: string, ...args: any[]): void {
+        if (this.isEnabled()) {
+            logger.info(`[WSX Reactive] ${message}`, ...args);
+        }
+    },
+};
+
+/**
+ * 增强的 reactive 函数，带调试支持
+ */
+export function reactiveWithDebug<T extends object>(
+    obj: T,
+    onChange: ReactiveCallback,
+    debugName?: string
+): T {
+    const name = debugName || obj.constructor.name || "Unknown";
+
+    return new Proxy(obj, {
+        set(target: T, key: string | symbol, value: any): boolean {
+            const oldValue = target[key as keyof T];
+
+            if (oldValue !== value) {
+                ReactiveDebug.log(`State change in ${name}:`, {
+                    key: String(key),
+                    oldValue,
+                    newValue: value,
+                });
+
+                target[key as keyof T] = value;
+                scheduler.schedule(onChange);
+            }
+
+            return true;
+        },
+
+        get(target: T, key: string | symbol): any {
+            return target[key as keyof T];
+        },
+    });
+}

package/src/utils/svg-utils.ts

@@ -0,0 +1,184 @@
+/**
+ * SVG utilities for namespace-aware element creation
+ */
+
+// SVG namespace URI
+export const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+
+// SVG专用元素 - 只存在于SVG中的元素
+export const SVG_ONLY_ELEMENTS = new Set([
+    // 结构元素 (Structural elements)
+    "svg",
+    "defs",
+    "g",
+    "symbol",
+    "use",
+
+    // 图形元素 (Graphics elements)
+    "circle",
+    "ellipse",
+    "line",
+    "path",
+    "polygon",
+    "polyline",
+    "rect",
+
+    // 文本元素 (Text elements)
+    "textPath",
+    "tspan",
+
+    // 渐变和模式 (Gradients and patterns)
+    "linearGradient",
+    "radialGradient",
+    "stop",
+    "pattern",
+
+    // 滤镜 (Filter elements)
+    "filter",
+    "feBlend",
+    "feColorMatrix",
+    "feComponentTransfer",
+    "feComposite",
+    "feConvolveMatrix",
+    "feDiffuseLighting",
+    "feDisplacementMap",
+    "feDistantLight",
+    "feDropShadow",
+    "feFlood",
+    "feFuncA",
+    "feFuncB",
+    "feFuncG",
+    "feFuncR",
+    "feGaussianBlur",
+    "feImage",
+    "feMerge",
+    "feMergeNode",
+    "feMorphology",
+    "feOffset",
+    "fePointLight",
+    "feSpecularLighting",
+    "feSpotLight",
+    "feTile",
+    "feTurbulence",
+
+    // 动画元素 (Animation elements)
+    "animate",
+    "animateMotion",
+    "animateTransform",
+    "set",
+
+    // 其他元素 (Other elements)
+    "clipPath",
+    "foreignObject",
+    "marker",
+    "mask",
+    "metadata",
+    "switch",
+    "desc",
+]);
+
+// 既存在于HTML又存在于SVG的元素 - 默认使用HTML版本
+export const DUAL_ELEMENTS = new Set(["image", "style", "title", "text"]);
+
+// 强制使用HTML版本的元素（即使在SVG上下文中）
+export const FORCE_HTML_ELEMENTS = new Set(["a"]);
+
+// 所有SVG元素的集合
+export const SVG_ELEMENTS = new Set([
+    ...SVG_ONLY_ELEMENTS,
+    ...DUAL_ELEMENTS,
+    ...FORCE_HTML_ELEMENTS,
+]);
+
+// SVG上下文追踪
+let svgContext = false;
+
+/**
+ * 检查标签名是否为SVG专用元素
+ */
+export function isSVGOnlyElement(tagName: string): boolean {
+    return SVG_ONLY_ELEMENTS.has(tagName);
+}
+
+/**
+ * 检查标签名是否为双重元素（HTML和SVG都有）
+ */
+export function isDualElement(tagName: string): boolean {
+    return DUAL_ELEMENTS.has(tagName);
+}
+
+/**
+ * 检查标签名是否为强制HTML元素
+ */
+export function isForceHTMLElement(tagName: string): boolean {
+    return FORCE_HTML_ELEMENTS.has(tagName);
+}
+
+/**
+ * 检查标签名是否为SVG元素（保持向后兼容）
+ */
+export function isSVGElement(tagName: string): boolean {
+    return SVG_ELEMENTS.has(tagName);
+}
+
+/**
+ * 设置SVG上下文状态
+ */
+export function setSVGContext(inSVG: boolean): void {
+    svgContext = inSVG;
+}
+
+/**
+ * 获取当前SVG上下文状态
+ */
+export function getSVGContext(): boolean {
+    return svgContext;
+}
+
+/**
+ * 创建元素 - 基于上下文和元素类型智能选择命名空间
+ */
+export function createElement(tagName: string): HTMLElement | SVGElement {
+    // 强制HTML元素始终使用HTML版本
+    if (isForceHTMLElement(tagName)) {
+        return document.createElement(tagName) as HTMLElement;
+    }
+
+    // SVG专用元素始终使用SVG命名空间
+    if (isSVGOnlyElement(tagName)) {
+        setSVGContext(true); // 进入SVG上下文
+        return document.createElementNS(SVG_NAMESPACE, tagName) as SVGElement;
+    }
+
+    // 双重元素根据上下文决定
+    if (isDualElement(tagName)) {
+        if (svgContext) {
+            return document.createElementNS(SVG_NAMESPACE, tagName) as SVGElement;
+        }
+    }
+
+    // 默认创建HTML元素
+    return document.createElement(tagName) as HTMLElement;
+}
+
+/**
+ * 检测元素是否需要在SVG上下文中处理
+ */
+export function shouldUseSVGNamespace(tagName: string): boolean {
+    return isSVGOnlyElement(tagName) || (isDualElement(tagName) && svgContext);
+}
+
+/**
+ * SVG特殊属性映射 - 处理SVG和HTML属性差异
+ */
+export const SVG_ATTRIBUTE_MAP = new Map([
+    ["className", "class"],
+    ["htmlFor", "for"],
+]);
+
+/**
+ * 获取SVG元素的正确属性名
+ */
+export function getSVGAttributeName(attributeName: string): string {
+    return SVG_ATTRIBUTE_MAP.get(attributeName) || attributeName;
+}

package/src/web-component.ts

@@ -0,0 +1,250 @@
+/**
+ * 通用 WSX Web Component 基础抽象类
+ *
+ * 提供JSX + CSS文件支持的通用基础类：
+ * - 抽象render方法强制子类实现JSX渲染
+ * - 自动集成StyleManager处理外部CSS
+ * - 提供完整的Web Component生命周期
+ * - 完全通用，不依赖任何特定框架
+ */
+
+import { h, type JSXChildren } from "./jsx-factory";
+import { StyleManager } from "./styles/style-manager";
+
+/**
+ * Web Component 配置接口
+ */
+export interface WebComponentConfig {
+    styles?: string; // CSS内容
+    styleName?: string; // 样式名称，用于缓存
+    [key: string]: unknown;
+}
+
+/**
+ * 通用 WSX Web Component 基础抽象类
+ */
+export abstract class WebComponent extends HTMLElement {
+    declare shadowRoot: ShadowRoot;
+    protected config: WebComponentConfig;
+    protected connected: boolean = false;
+
+    /**
+     * 子类应该重写这个方法来定义观察的属性
+     * @returns 要观察的属性名数组
+     */
+    static get observedAttributes(): string[] {
+        return [];
+    }
+
+    constructor(config: WebComponentConfig = {}) {
+        super();
+
+        this.config = config;
+        this.attachShadow({ mode: "open" });
+
+        // 自动应用CSS样式
+        if (config.styles) {
+            const styleName = config.styleName || this.constructor.name;
+            StyleManager.applyStyles(this.shadowRoot, styleName, config.styles);
+        }
+    }
+
+    /**
+     * 抽象方法：子类必须实现JSX渲染
+     *
+     * @returns JSX元素
+     */
+    abstract render(): HTMLElement;
+
+    /**
+     * Web Component生命周期：连接到DOM
+     */
+    connectedCallback(): void {
+        this.connected = true;
+        try {
+            // 渲染JSX内容到Shadow DOM
+            const content = this.render();
+            this.shadowRoot.appendChild(content);
+
+            // 调用子类的初始化钩子
+            this.onConnected?.();
+        } catch (error) {
+            console.error(`[${this.constructor.name}] Error in connectedCallback:`, error);
+            this.renderError(error);
+        }
+    }
+
+    /**
+     * Web Component生命周期：从DOM断开
+     */
+    disconnectedCallback(): void {
+        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;
+
+    /**
+     * 查找Shadow DOM内的元素
+     *
+     * @param selector - CSS选择器
+     * @returns 元素或null
+     */
+    public querySelector<T extends HTMLElement>(selector: string): T | null {
+        return this.shadowRoot.querySelector<T>(selector);
+    }
+
+    /**
+     * 查找Shadow DOM内的所有匹配元素
+     *
+     * @param selector - CSS选择器
+     * @returns 元素列表
+     */
+    public querySelectorAll<T extends HTMLElement>(selector: string): NodeListOf<T> {
+        return this.shadowRoot.querySelectorAll<T>(selector);
+    }
+
+    /**
+     * 重新渲染组件
+     */
+    protected rerender(): void {
+        if (!this.connected) {
+            console.warn(
+                `[${this.constructor.name}] Component is not connected, skipping rerender.`
+            );
+            return;
+        }
+        // 保存当前的 adopted stylesheets (jsdom may not support this)
+        const adoptedStyleSheets = this.shadowRoot.adoptedStyleSheets || [];
+
+        // 清空现有内容但保留样式
+        this.shadowRoot.innerHTML = "";
+
+        // 恢复 adopted stylesheets (避免重新应用样式)
+        if (this.shadowRoot.adoptedStyleSheets) {
+            this.shadowRoot.adoptedStyleSheets = adoptedStyleSheets;
+        }
+
+        // 只有在没有 adopted stylesheets 时才重新应用样式
+        if (adoptedStyleSheets.length === 0 && this.config.styles) {
+            const styleName = this.config.styleName || this.constructor.name;
+            StyleManager.applyStyles(this.shadowRoot, styleName, this.config.styles);
+        }
+
+        // 重新渲染JSX
+        try {
+            const content = this.render();
+            this.shadowRoot.appendChild(content);
+        } catch (error) {
+            console.error(`[${this.constructor.name}] Error in rerender:`, error);
+            this.renderError(error);
+        }
+    }
+
+    /**
+     * 渲染错误信息
+     *
+     * @param error - 错误对象
+     */
+    private renderError(error: unknown): void {
+        // 清空现有内容
+        this.shadowRoot.innerHTML = "";
+
+        const errorElement = h(
+            "div",
+            {
+                style: "color: red; padding: 10px; border: 1px solid red; background: #ffe6e6; font-family: monospace;",
+            },
+            [
+                h("strong", {}, `[${this.constructor.name}] Component Error:`),
+                h("pre", { style: "margin: 10px 0; white-space: pre-wrap;" }, String(error)),
+            ]
+        );
+
+        this.shadowRoot.appendChild(errorElement);
+    }
+
+    /**
+     * 获取配置值
+     *
+     * @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;
+    }
+
+    /**
+     * 获取属性值
+     *
+     * @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助手
+export { h };
+export type { JSXChildren };

package/types/css-inline.d.ts

@@ -0,0 +1,4 @@
+declare module "*.css?inline" {
+    const styles: string;
+    export default styles;
+}

package/types/index.d.ts

@@ -0,0 +1,32 @@
+// 导入所有类型定义
+import "./css-inline.d.ts";
+import "./wsx-types";
+import "./global.d.ts";
+
+// 重新导出 JSX 工厂函数和类型
+export { h, Fragment } from "./wsx-types";
+export type { JSXChildren } from "../src/jsx-factory";
+
+// 导出 WebComponent 类和配置
+export { WebComponent, type WebComponentConfig } from "../src/web-component";
+
+// 导出 auto-register 相关类型和函数
+export {
+    autoRegister,
+    registerComponent,
+    registerAll,
+    isRegistered,
+    getTagName,
+} from "../src/auto-register";
+export type { AutoRegistrationOptions } from "../src/auto-register";
+
+// 导出 StyleManager
+export { StyleManager } from "../src/styles/style-manager";
+
+// 导出 Logger 相关类型和函数
+export { WSXLogger, logger, createLogger } from "../src/utils/logger.ts";
+export type { Logger, LogLevel } from "../src/utils/logger.ts";
+
+// 重新导出 JSX 运行时
+export { h as jsx, h as jsxs, Fragment as F } from "../src/jsx-factory";
+export type { JSXChildren as J } from "../src/jsx-factory";

package/types/jsx-runtime.d.ts

@@ -0,0 +1,2 @@
+export { h as jsx, h as jsxs, Fragment } from "./wsx-types";
+export type { JSX } from "./jsx";

package/types/jsx.d.ts

@@ -0,0 +1,28 @@
+/**
+ * JSX 专用类型声明文件
+ * 为 jsxImportSource 机制提供类型支持
+ */
+
+// 导入全局 JSX 类型声明
+import "./wsx-types";
+
+// 导出 JSX 工厂函数
+export { h, Fragment } from "./wsx-types";
+
+// JSX namespace declaration for TypeScript
+export namespace JSX {
+    type Element = HTMLElement;
+
+    interface IntrinsicElements {
+        // HTML elements
+        [elemName: string]: object;
+    }
+
+    interface ElementAttributesProperty {
+        props: object;
+    }
+
+    interface ElementChildrenAttribute {
+        children: object;
+    }
+}