@wsxjs/wsx-core 0.0.19 → 0.0.21

package/src/utils/cache-key.ts

@@ -0,0 +1,114 @@
+/**
+ * Cache Key Generation Utilities
+ *
+ * Pure functions for generating cache keys for DOM elements (RFC 0037).
+ * These functions are used by the jsx-factory to identify and cache DOM elements.
+ */
+
+import { RenderContext } from "../render-context";
+import type { BaseComponent } from "../base-component";
+
+/**
+ * Internal symbol for position ID (used by Babel plugin in future)
+ * For now, we use a string key for backward compatibility
+ */
+const POSITION_ID_KEY = "__wsxPositionId";
+
+/**
+ * Internal symbol for index (used in list scenarios)
+ */
+const INDEX_KEY = "__wsxIndex";
+
+/**
+ * Component-level element counters (using WeakMap to avoid memory leaks)
+ * Each component instance maintains its own counter to ensure unique cache keys
+ * when position ID is not available.
+ */
+const componentElementCounters = new WeakMap<BaseComponent, number>();
+
+/**
+ * Component ID cache (using WeakMap to avoid memory leaks)
+ * Caches component IDs to avoid recomputing them on every render.
+ */
+const componentIdCache = new WeakMap<BaseComponent, string>();
+
+/**
+ * Generates a cache key for a DOM element.
+ *
+ * Cache key format: `${componentId}:${tag}:${identifier}`
+ *
+ * Priority:
+ * 1. User-provided key (if exists) - most reliable
+ * 2. Index (if in list scenario)
+ * 3. Position ID (if provided and valid)
+ * 4. Component-level counter (runtime fallback, ensures uniqueness)
+ * 5. Timestamp fallback (last resort, ensures uniqueness)
+ *
+ * @param tag - HTML tag name
+ * @param props - Element props (may contain position ID, index, or key)
+ * @param componentId - Component instance ID (from RenderContext)
+ * @param component - Optional component instance (for counter-based fallback)
+ * @returns Cache key string
+ */
+export function generateCacheKey(
+    tag: string,
+    props: Record<string, unknown> | null | undefined,
+    componentId: string,
+    component?: BaseComponent
+): string {
+    const positionId = props?.[POSITION_ID_KEY];
+    const userKey = props?.key;
+    const index = props?.[INDEX_KEY];
+
+    // 优先级 1: 用户 key（最可靠）
+    if (userKey !== undefined && userKey !== null) {
+        return `${componentId}:${tag}:key-${String(userKey)}`;
+    }
+
+    // 优先级 2: 索引（列表场景）
+    if (index !== undefined && index !== null) {
+        return `${componentId}:${tag}:idx-${String(index)}`;
+    }
+
+    // 优先级 3: 位置 ID（编译时注入，如果有效）
+    if (positionId !== undefined && positionId !== null && positionId !== "no-id") {
+        return `${componentId}:${tag}:${String(positionId)}`;
+    }
+
+    // 优先级 4: 组件级别计数器（运行时回退，确保唯一性）
+    if (component) {
+        let counter = componentElementCounters.get(component) || 0;
+        counter++;
+        componentElementCounters.set(component, counter);
+        return `${componentId}:${tag}:auto-${counter}`;
+    }
+
+    // 最后回退：时间戳（不推荐，但确保唯一性）
+    return `${componentId}:${tag}:fallback-${Date.now()}-${Math.random()}`;
+}
+
+/**
+ * Gets the component ID from the current render context.
+ * Falls back to 'unknown' if no context is available.
+ * Uses caching to avoid recomputing the ID on every call.
+ *
+ * @returns Component ID string
+ */
+export function getComponentId(): string {
+    const component = RenderContext.getCurrentComponent();
+    if (component) {
+        // Check cache first
+        let cachedId = componentIdCache.get(component);
+        if (cachedId) {
+            return cachedId;
+        }
+
+        // Compute and cache
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const instanceId = (component as any)._instanceId || "default";
+        cachedId = `${component.constructor.name}:${instanceId}`;
+        componentIdCache.set(component, cachedId);
+        return cachedId;
+    }
+    return "unknown";
+}

package/src/utils/dom-utils.ts

@@ -4,6 +4,18 @@
  * Provides helper functions for DOM manipulation and HTML parsing
  */
 
+// JSX子元素类型
+export type JSXChildren =
+    | string
+    | number
+    | HTMLElement
+    | SVGElement
+    | DocumentFragment
+    | JSXChildren[]
+    | null
+    | undefined
+    | boolean;
+
 /**
  * Convert HTML string to DOM nodes (elements and text)
  *
@@ -46,3 +58,110 @@ export function parseHTMLToNodes(html: string): (HTMLElement | SVGElement | stri
         }
     });
 }
+
+/**
+ * 检测字符串是否包含HTML标签
+ * 使用更严格的检测：必须包含完整的 HTML 标签（开始和结束标签，或自闭合标签）
+ */
+export 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）
+ */
+export function flattenChildren(
+    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
+        | HTMLElement
+        | SVGElement
+        | DocumentFragment
+        | boolean
+        | null
+        | undefined
+    )[] = [];
+
+    for (const child of children) {
+        if (child === null || child === undefined || child === false) {
+            continue;
+        } else if (Array.isArray(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);
+        }
+    }
+
+    return result;
+}

package/src/utils/element-creation.ts

@@ -0,0 +1,140 @@
+/**
+ * Element Creation Utilities
+ *
+ * Pure functions for creating DOM elements and applying props/children.
+ * Extracted from jsx-factory.ts to keep functions small and focused.
+ */
+
+import { createElement, shouldUseSVGNamespace, getSVGAttributeName } from "./svg-utils";
+import { flattenChildren, type JSXChildren } from "./dom-utils";
+import { setSmartProperty, isFrameworkInternalProp } from "./props-utils";
+
+/**
+ * Applies a single prop to an element.
+ */
+function applySingleProp(
+    element: HTMLElement | SVGElement,
+    key: string,
+    value: unknown,
+    tag: string,
+    isSVG: boolean
+): void {
+    if (value === null || value === undefined || value === false) {
+        return;
+    }
+
+    // 处理ref回调
+    if (key === "ref" && typeof value === "function") {
+        value(element);
+        return;
+    }
+
+    // 处理className和class
+    if (key === "className" || key === "class") {
+        if (isSVG) {
+            element.setAttribute("class", value as string);
+        } else {
+            (element as HTMLElement).className = value as string;
+        }
+        return;
+    }
+
+    // 处理style
+    if (key === "style" && typeof value === "string") {
+        element.setAttribute("style", value);
+        return;
+    }
+
+    // 处理事件监听器
+    if (key.startsWith("on") && typeof value === "function") {
+        const eventName = key.slice(2).toLowerCase();
+        element.addEventListener(eventName, value as EventListener);
+        return;
+    }
+
+    // 处理布尔属性
+    if (typeof value === "boolean") {
+        if (value) {
+            element.setAttribute(key, "");
+        }
+        return;
+    }
+
+    // 特殊处理 input/textarea/select 的 value 属性
+    if (key === "value") {
+        if (
+            element instanceof HTMLInputElement ||
+            element instanceof HTMLTextAreaElement ||
+            element instanceof HTMLSelectElement
+        ) {
+            element.value = String(value);
+        } else {
+            const attributeName = isSVG ? getSVGAttributeName(key) : key;
+            element.setAttribute(attributeName, String(value));
+        }
+        return;
+    }
+
+    // 过滤框架内部属性（不应该渲染到 DOM）
+    if (isFrameworkInternalProp(key)) {
+        return;
+    }
+
+    // 处理其他属性 - 使用智能属性设置函数
+    setSmartProperty(element, key, value, tag);
+}
+
+/**
+ * Applies all props to an element.
+ */
+export function applyPropsToElement(
+    element: HTMLElement | SVGElement,
+    props: Record<string, unknown> | null,
+    tag: string
+): void {
+    if (!props) {
+        return;
+    }
+
+    const isSVG = shouldUseSVGNamespace(tag);
+    Object.entries(props).forEach(([key, value]) => {
+        applySingleProp(element, key, value, tag, isSVG);
+    });
+}
+
+/**
+ * Appends children to an element.
+ */
+export function appendChildrenToElement(
+    element: HTMLElement | SVGElement,
+    children: JSXChildren[]
+): void {
+    const flatChildren = flattenChildren(children);
+    flatChildren.forEach((child) => {
+        if (child === null || child === undefined || child === false) {
+            return;
+        }
+
+        if (typeof child === "string" || typeof child === "number") {
+            element.appendChild(document.createTextNode(String(child)));
+        } else if (child instanceof HTMLElement || child instanceof SVGElement) {
+            element.appendChild(child);
+        } else if (child instanceof DocumentFragment) {
+            element.appendChild(child);
+        }
+    });
+}
+
+/**
+ * Creates an element and applies props and children.
+ */
+export function createElementWithPropsAndChildren(
+    tag: string,
+    props: Record<string, unknown> | null,
+    children: JSXChildren[]
+): HTMLElement | SVGElement {
+    const element = createElement(tag);
+    applyPropsToElement(element, props, tag);
+    appendChildrenToElement(element, children);
+    return element;
+}

package/src/utils/element-marking.ts

@@ -0,0 +1,80 @@
+/**
+ * Element Marking Utilities
+ *
+ * Pure functions for marking and identifying DOM elements created by h() (RFC 0037).
+ * Core rule: All elements created by h() must be marked with __wsxCacheKey.
+ * Unmarked elements (custom elements, third-party library injected) should be preserved.
+ */
+
+/**
+ * Internal property name for cache key on DOM elements
+ */
+const CACHE_KEY_PROP = "__wsxCacheKey";
+
+/**
+ * Marks an element with a cache key.
+ * This marks the element as created by h() and eligible for framework management.
+ *
+ * @param element - DOM element to mark
+ * @param cacheKey - Cache key to store on the element
+ */
+export function markElement(element: HTMLElement | SVGElement, cacheKey: string): void {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (element as any)[CACHE_KEY_PROP] = cacheKey;
+}
+
+/**
+ * Gets the cache key from an element.
+ * Returns null if the element is not marked (not created by h()).
+ *
+ * @param element - DOM element to check
+ * @returns Cache key string or null
+ */
+export function getElementCacheKey(element: HTMLElement | SVGElement): string | null {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const key = (element as any)[CACHE_KEY_PROP];
+    return key !== undefined ? String(key) : null;
+}
+
+/**
+ * Checks if an element was created by h().
+ * Core rule: Elements with __wsxCacheKey are created by h() and can be managed by the framework.
+ * Elements without this mark should be preserved (custom elements, third-party library injected).
+ *
+ * @param element - DOM element to check
+ * @returns True if element was created by h()
+ */
+export function isCreatedByH(element: Node): boolean {
+    if (!(element instanceof HTMLElement || element instanceof SVGElement)) {
+        return false;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (element as any)[CACHE_KEY_PROP] !== undefined;
+}
+
+/**
+ * Checks if an element should be preserved during DOM updates.
+ * Core rule: Unmarked elements (custom elements, third-party library injected) should be preserved.
+ *
+ * @param element - DOM element to check
+ * @returns True if element should be preserved
+ */
+export function shouldPreserveElement(element: Node): boolean {
+    // 规则 1: 非元素节点保留
+    if (!(element instanceof HTMLElement || element instanceof SVGElement)) {
+        return true;
+    }
+
+    // 规则 2: 没有标记的元素保留（自定义元素、第三方库注入）
+    if (!isCreatedByH(element)) {
+        return true;
+    }
+
+    // 规则 3: 显式标记保留
+    if (element.hasAttribute("data-wsx-preserve")) {
+        return true;
+    }
+
+    // 规则 4: 由 h() 创建的元素 → 不保留（由框架管理）
+    return false;
+}