@lytjs/adapter-web 6.0.0

package/dist/index.d.cts

@@ -0,0 +1,581 @@
+import { RendererHost, HostStyleDeclaration, HostEventHandler, HostEventOptions, HostRect, TransitionDurationInfo, HostEvent } from '@lytjs/host-contract';
+import { VNode, ComponentInternalInstance, SuspenseBoundary, RendererOptions } from '@lytjs/vdom';
+export { getEventKey, normalizeEventName, parseEventModifier } from '@lytjs/common-events';
+export { patchAttr, patchClass, patchStyle } from '@lytjs/common-dom';
+
+/**
+ * @lytjs/adapter-web - WebRendererHost
+ * 浏览器 DOM 平台的 RendererHost<Node, Element> 实现。
+ *
+ * 所有 DOM API 调用集中在此文件内，不泄漏到 L1/L2。
+ * 极度轻薄：只做纯翻译，不做队列/兼容/归一化。
+ * FIX: P2-33 强制同步布局优化 - 添加缓存和批量处理
+ */
+
+/**
+ * Web 平台渲染宿主实现。
+ *
+ * 实现 RendererHost<Node, Element> 接口，将所有操作直接翻译为浏览器 DOM API。
+ */
+declare class WebRendererHost implements RendererHost<Node, Element> {
+    readonly __isRendererHost: true;
+    private static readonly wrappedHandlerMap;
+    private static getWrappedHandler;
+    private static setWrappedHandler;
+    /**
+     * 创建元素节点。
+     * SVG 标签使用 createElementNS，普通标签使用 createElement。
+     */
+    createElement(tag: string, isSVG?: boolean): Element;
+    /** 创建文本节点 */
+    createText(text: string): Node;
+    /** 创建注释节点 */
+    createComment(text: string): Node;
+    /** 设置元素文本内容（覆盖所有子节点） */
+    setElementText(node: Element, text: string): void;
+    /** 设置文本/注释节点的内容 */
+    setText(node: Node, text: string): void;
+    /**
+     * 在父节点的 anchor 前插入子节点。
+     * anchor 为 null 时追加到末尾。
+     */
+    insert(child: Node, parent: Node, anchor?: Node | null): void;
+    /** 从父节点移除子节点 */
+    remove(child: Node): void;
+    /** 获取下一个兄弟节点 */
+    nextSibling(node: Node): Node | null;
+    /** 获取父节点 */
+    parentNode(node: Node): Node | null;
+    /**
+     * 查询选择器。
+     */
+    querySelector(selector: string): Element | null;
+    /**
+     * 统一属性 patch 入口。
+     * 委托给 web-patch-props.ts 处理 class/style/event/attr 分发。
+     */
+    patchProp(el: Element, key: string, prevValue: unknown, nextValue: unknown, isSVG?: boolean): void;
+    /** 添加 CSS 类名 */
+    addClass(el: Element, cls: string): void;
+    /** 移除 CSS 类名 */
+    removeClass(el: Element, cls: string): void;
+    /** 检查是否包含 CSS 类名 */
+    hasClass(el: Element, cls: string): boolean;
+    /**
+     * 设置内联样式属性。
+     * value 为 null/undefined 时移除该样式属性。
+     * FIX: P2-v11-35 添加 SVG 元素兼容检查，
+     * SVG 元素的 style 属性是 CSSStyleDeclaration 但部分属性名不同，
+     * 使用 setProperty/removeProperty 统一处理
+     */
+    setStyle(el: Element, key: string, value: string | null | undefined): void;
+    /**
+     * 移除内联样式属性
+     * FIX: P2-16 统一实现风格，与 setStyle 保持一致
+     */
+    removeStyle(el: Element, key: string): void;
+    /**
+     * 获取计算样式。
+     */
+    getComputedStyle(el: Element): HostStyleDeclaration;
+    /**
+     * 强制回流/重排。
+     * 读取 offsetHeight 触发浏览器同步布局。
+     * FIX: P2-33 强制同步布局优化 - 添加缓存避免重复读取
+     */
+    forceReflow(el: Element): void;
+    /**
+     * 获取元素尺寸（带缓存）
+     * FIX: P2-33 强制同步布局优化
+     */
+    getElementSize(el: Element): {
+        width: number;
+        height: number;
+    };
+    /**
+     * 添加事件监听器。
+     * 将原生 DOM Event 包装为 HostEvent 后传递给 handler。
+     * 返回一个取消监听的函数。
+     */
+    addEventListener(el: Element, event: string, handler: HostEventHandler, options?: HostEventOptions): () => void;
+    /**
+     * 移除事件监听器。
+     */
+    removeEventListener(el: Element, event: string, handler: HostEventHandler, options?: HostEventOptions): void;
+    /**
+     * 获取元素的几何边界信息。
+     */
+    getBoundingClientRect(el: Element): HostRect;
+    /** 获取元素的指定属性值 */
+    getAttribute(el: Element, key: string): string | null;
+    /**
+     * 获取过渡/动画时长信息。
+     * 通过读取计算样式中的 transition-duration / animation-duration 获取。
+     */
+    getTransitionInfo(el: Element, _type: 'enter' | 'leave'): TransitionDurationInfo;
+    /**
+     * 请求下一帧回调（双 rAF 确保浏览器已绘制）。
+     */
+    nextFrame(fn: () => void): void;
+    /**
+     * 延迟执行。
+     */
+    setTimeout(fn: () => void, ms: number): number;
+    /** 取消延迟执行 */
+    clearTimeout(id: number): void;
+    /**
+     * 获取元素的 namespaceURI（用于 SVG 检测）。
+     */
+    getNamespaceURI(el: Element): string | null;
+    /**
+     * 替换子节点（用于 hydration mismatch 处理）。
+     */
+    replaceChild(parent: Node, newChild: Node, oldChild: Node): void;
+    /**
+     * 获取子节点列表（用于 hydration）。
+     */
+    getChildNodes(el: Element): Node[];
+    /**
+     * 获取节点类型（用于 hydration 判断）。
+     */
+    getNodeType(node: Node): number;
+    /**
+     * 获取元素标签名（用于 hydration 匹配）。
+     * 返回小写标签名。
+     */
+    getTagName(el: Element): string;
+}
+
+/**
+ * @lytjs/adapter-web - DOM Renderer
+ * 使用 WebRendererHost 创建 DOM 渲染器。
+ *
+ * 从 @lytjs/renderer/src/dom/dom-renderer.ts 迁移，
+ * 使用 WebRendererHost 替代 createDOMRendererOptions。
+ * 保留 vnodeMap (WeakMap) 和 cleanupVNodeResources 逻辑。
+ * FIX: P2-31 DOM 操作合并优化 - 批量处理 DOM 操作
+ */
+
+interface DOMRenderer {
+    render(vnode: VNode | null, container: Element): void;
+    patch(n1: VNode | null, n2: VNode, container: Node, anchor?: Node | null): void;
+    unmount(vnode: VNode): void;
+    mount(vnode: VNode, container: Node): void;
+    move(vnode: VNode, container: Node, anchor: Node | null, _parentComponent?: ComponentInternalInstance | null, _parentSuspense?: SuspenseBoundary | null): void;
+}
+/**
+ * 创建 DOM 渲染器。
+ *
+ * 使用 WebRendererHost 作为平台适配层，通过 vdom 的 createRenderer
+ * 创建完整的渲染器实例。vnodeMap 通过闭包作用域隔离。
+ *
+ * @param extraOptions 可选的额外渲染器选项，例如 setupChildComponent
+ */
+declare function createDOMRenderer(extraOptions?: Partial<Pick<RendererOptions<Node, Element>, 'setupChildComponent' | 'normalizeProps'>>): DOMRenderer;
+
+/**
+ * @lytjs/adapter-web - Hydration
+ * 简化的水合逻辑，将现有 DOM 节点与 vnode 匹配。
+ *
+ * 从 @lytjs/renderer/src/dom/hydration.ts 迁移，
+ * 使用 WebRendererHost 的 getChildNodes/getNodeType/getTagName 等方法。
+ */
+
+interface HydrationRenderer {
+    hydrate(vnode: VNode, container: HTMLElement): void;
+}
+/**
+ * 创建水合函数，用于将现有 DOM 与 vnode 匹配。
+ *
+ * @param _rendererOptions - 保留用于未来渲染器配置（当前未使用）
+ * @param sharedVnodeMap - 可选的共享 vnodeMap，使水合和 DOM 渲染器使用同一映射
+ */
+declare function createHydrationFunctions(_rendererOptions: Record<string, unknown>, sharedVnodeMap?: WeakMap<Element, VNode | null>): HydrationRenderer;
+
+/**
+ * @lytjs/adapter-web - DOM Event Wrapping
+ * 将原生 DOM Event 包装为平台无关的 HostEvent。
+ */
+
+/**
+ * 将原生 DOM Event 包装为 HostEvent。
+ *
+ * 纯翻译层，不做任何归一化或兼容处理。
+ *
+ * @param e - 原生 DOM Event
+ * @returns HostEvent 实例
+ */
+declare function wrapDOMEvent(e: Event): HostEvent;
+
+/**
+ * @lytjs/adapter-web - Event Invoker Caching with Pooling
+ * 事件缓存 Invoker 模式：通过 el._vei 缓存事件处理函数，
+ * 更新时仅替换 invoker.value，无需重新 addEventListener。
+ *
+ * FIX: P1-12 DOM-NEW-01 - 实现事件监听器池化，复用事件监听器对象
+ * 通过对象池复用 invoker 对象，减少内存分配和垃圾回收压力
+ */
+/** 事件修饰符解析结果 */
+interface ParsedEvent {
+    /** 规范化后的事件名，如 'click' */
+    name: string;
+    /** 是否调用 e.stopPropagation() */
+    stop: boolean;
+    /** 是否调用 e.preventDefault() */
+    prevent: boolean;
+    /** 是否使用 capture 模式 */
+    capture: boolean;
+    /** 是否使用 once 模式 */
+    once: boolean;
+    /** 是否仅在 e.target === el 时触发 */
+    self: boolean;
+    /** 是否使用 passive 模式 */
+    passive: boolean;
+}
+/** 事件 invoker 函数，持有 value 属性用于更新 */
+interface EventInvoker extends EventListener {
+    /** 当前绑定的事件处理函数，更新时直接替换此属性 */
+    value: ((...args: unknown[]) => void) | null;
+    /** @internal 解析后的事件修饰符 */
+    _parsed?: ParsedEvent;
+}
+/**
+ * 创建事件 invoker 函数。
+ * invoker 是一个持有 value 属性的闭包，调用时执行 invoker.value(event)。
+ * FIX: P1-12 DOM-NEW-01 - 优先从对象池获取 invoker 对象
+ */
+declare function createInvoker(initialValue: (...args: unknown[]) => void): EventInvoker;
+/**
+ * 更新元素上的事件监听。
+ *
+ * 四种情况：
+ * 1. nextValue && existingInvoker → 直接替换 invoker.value（O(1) 赋值）
+ * 2. nextValue && !existingInvoker → 创建 invoker，addEventListener
+ * 3. !nextValue && existingInvoker → removeEventListener，清除缓存
+ * 4. !nextValue && !existingInvoker → 无操作
+ */
+declare function patchEvent(el: Element, rawName: string, nextValue: ((...args: unknown[]) => void) | null, _prevValue?: ((...args: unknown[]) => void) | null): void;
+/**
+ * 移除元素上所有通过 invoker 缓存的事件监听。
+ * 用于组件卸载时的清理。
+ * FIX: P1-12 DOM-NEW-01 - 将 invoker 对象归还到对象池以复用
+ */
+declare function removeAllEventListeners(el: Element): void;
+
+/**
+ * @lytjs/adapter-web - DOM Property Patching
+ * Enhanced patchProp for DOM elements with class, style, event, and attribute handling.
+ * Delegates shared logic to @lytjs/common-dom, event caching to web-patch-events.
+ *
+ * 从 @lytjs/renderer/src/dom/patch-props.ts 迁移，纯翻译，不做额外归一化。
+ *
+ * TODO (P2-13): Vendor prefix 处理为未来优化项。
+ * 当前未对 CSS 属性和 DOM 属性做 vendor prefix 自动转换（如 webkitTransform -> -webkit-transform）。
+ * 现代浏览器已逐步移除对 vendor prefix 的需求，但在需要兼容旧版浏览器的场景下，
+ * 可考虑在 patchStyle 和 patchAttr 中添加自动 prefix 检测与转换逻辑。
+ */
+
+/**
+ * Patch a prop on a DOM element.
+ * Delegates class/style/attr/innerHTML/textContent to @lytjs/common-dom,
+ * and uses invoker-based event handling from web-patch-events.
+ */
+declare function patchProp(el: Element, key: string, prevValue: unknown, nextValue: unknown, isSVG?: boolean): void;
+
+/**
+ * @lytjs/adapter-web - Extended Web Host
+ *
+ * 扩展 RendererHost 接口，添加更多宿主能力支持
+ * (merged from @lytjs/host)
+ *
+ * @module @lytjs/adapter-web
+ * @version 6.0.0
+ */
+
+/**
+ * 扩展的 RendererHost 接口
+ * 在基础 RendererHost 上添加了更多宿主操作方法
+ */
+interface ExtendedRendererHost<HN = unknown, HE extends HN = HN> extends RendererHost<HN, HE> {
+    /**
+     * 在父节点的指定子节点之前插入新子节点
+     * 如果 referenceNode 为 null，则在末尾追加
+     *
+     * @param parent - 父节点
+     * @param newChild - 要插入的新子节点
+     * @param referenceNode - 参考子节点，新节点将插入其之前
+     *
+     * @example
+     * ```ts
+     * // 在 child2 之前插入 newChild
+     * host.insertBefore(parent, newChild, child2)
+     * // parent 的子节点顺序: [child1, newChild, child2, child3]
+     * ```
+     */
+    insertBefore(parent: HN, newChild: HN, referenceNode: HN | null): void;
+    /**
+     * 替换父节点中的子节点
+     *
+     * @param parent - 父节点
+     * @param newChild - 新子节点
+     * @param oldChild - 要被替换的旧子节点
+     * @returns 被替换的旧子节点
+     *
+     * @example
+     * ```ts
+     * // 用 newChild 替换 oldChild
+     * host.replaceChild(parent, newChild, oldChild)
+     * ```
+     */
+    replaceChild(parent: HN, newChild: HN, oldChild: HN): HN;
+    /**
+     * 获取元素的第一个子节点
+     *
+     * @param node - 宿主节点
+     * @returns 第一个子节点，如果没有则返回 null
+     */
+    firstChild?(node: HN): HN | null;
+    /**
+     * 获取元素的最后一个子节点
+     *
+     * @param node - 宿主节点
+     * @returns 最后一个子节点，如果没有则返回 null
+     */
+    lastChild?(node: HN): HN | null;
+    /**
+     * 检查一个节点是否包含另一个节点
+     *
+     * @param parent - 父节点
+     * @param child - 子节点
+     * @returns 如果包含则返回 true
+     */
+    contains?(parent: HN, child: HN): boolean;
+    /**
+     * 获取元素的所有属性名
+     *
+     * @param el - 宿主元素
+     * @returns 属性名数组
+     */
+    getAttributeNames?(el: HE): string[];
+    /**
+     * 批量设置属性
+     *
+     * @param el - 宿主元素
+     * @param attrs - 属性键值对
+     */
+    setAttributes?(el: HE, attrs: Record<string, unknown>): void;
+    /**
+     * 批量移除属性
+     *
+     * @param el - 宿主元素
+     * @param keys - 要移除的属性名数组
+     */
+    removeAttributes?(el: HE, keys: string[]): void;
+    /**
+     * 批量设置样式
+     *
+     * @param el - 宿主元素
+     * @param styles - 样式键值对
+     */
+    setStyles?(el: HE, styles: Record<string, string | null | undefined>): void;
+    /**
+     * 获取元素的所有 CSS 类名
+     *
+     * @param el - 宿主元素
+     * @returns 类名数组
+     */
+    getClassList?(el: HE): string[];
+    /**
+     * 切换 CSS 类名
+     *
+     * @param el - 宿主元素
+     * @param cls - 类名
+     * @param force - 如果为 true 则添加，false 则移除，省略则切换
+     * @returns 操作后类名是否存在
+     */
+    toggleClass?(el: HE, cls: string, force?: boolean): boolean;
+    /**
+     * 触发/分派事件
+     *
+     * @param el - 宿主元素
+     * @param event - 事件名或事件对象
+     * @param detail - 自定义事件详情数据
+     * @returns 事件是否被取消
+     */
+    dispatchEvent?(el: HE, event: string | HostEvent, detail?: unknown): boolean;
+    /**
+     * 一次性事件监听
+     *
+     * @param el - 宿主元素
+     * @param event - 事件名
+     * @param handler - 事件处理器
+     * @param options - 监听选项
+     */
+    onceEventListener?(el: HE, event: string, handler: HostEventHandler, options?: HostEventOptions): () => void;
+    /**
+     * 查询所有匹配选择器的元素
+     *
+     * @param selector - CSS 选择器
+     * @param context - 查询上下文（默认为 document）
+     * @returns 匹配的元素数组
+     */
+    querySelectorAll?(selector: string, context?: HN): HE[];
+    /**
+     * 通过 ID 获取元素
+     *
+     * @param id - 元素 ID
+     * @returns 元素或 null
+     */
+    getElementById?(id: string): HE | null;
+    /**
+     * 通过类名获取元素
+     *
+     * @param className - 类名
+     * @param context - 查询上下文
+     * @returns 元素数组
+     */
+    getElementsByClassName?(className: string, context?: HN): HE[];
+    /**
+     * 通过标签名获取元素
+     *
+     * @param tag - 标签名
+     * @param context - 查询上下文
+     * @returns 元素数组
+     */
+    getElementsByTagName?(tag: string, context?: HN): HE[];
+    /**
+     * 滚动元素到视图
+     *
+     * @param el - 宿主元素
+     * @param options - 滚动选项
+     */
+    scrollIntoView?(el: HE, options?: {
+        behavior?: 'auto' | 'smooth';
+        block?: 'start' | 'center' | 'end' | 'nearest';
+        inline?: 'start' | 'center' | 'end' | 'nearest';
+    }): void;
+    /**
+     * 获取元素的滚动位置
+     *
+     * @param el - 宿主元素（null 表示 document）
+     * @returns 滚动位置
+     */
+    getScrollPosition?(el?: HE | null): {
+        scrollLeft: number;
+        scrollTop: number;
+    };
+    /**
+     * 设置元素的滚动位置
+     *
+     * @param el - 宿主元素（null 表示 document）
+     * @param left - 水平滚动位置
+     * @param top - 垂直滚动位置
+     */
+    setScrollPosition?(el: HE | null, left: number, top: number): void;
+    /**
+     * 获取元素的尺寸信息
+     *
+     * @param el - 宿主元素
+     * @returns 尺寸信息
+     */
+    getElementSize?(el: HE): {
+        width: number;
+        height: number;
+        clientWidth: number;
+        clientHeight: number;
+        scrollWidth: number;
+        scrollHeight: number;
+    };
+    /**
+     * 获取元素相对于视口的位置
+     *
+     * @param el - 宿主元素
+     * @returns 位置信息
+     */
+    getElementOffset?(el: HE): {
+        left: number;
+        top: number;
+    };
+}
+/**
+ * 宿主能力标志
+ */
+interface HostCapabilities {
+    /** 支持 Shadow DOM */
+    shadowDOM: boolean;
+    /** 支持自定义元素 */
+    customElements: boolean;
+    /** 支持插槽（Slot） */
+    slots: boolean;
+    /** 支持模板（Template） */
+    template: boolean;
+    /** 支持 CSS 变量 */
+    cssVariables: boolean;
+    /** 支持 ResizeObserver */
+    resizeObserver: boolean;
+    /** 支持 IntersectionObserver */
+    intersectionObserver: boolean;
+    /** 支持 MutationObserver */
+    mutationObserver: boolean;
+    /** 支持 Web Animations API */
+    webAnimations: boolean;
+    /** 支持 CSS 动画 */
+    cssAnimations: boolean;
+    /** 支持 CSS 过渡 */
+    cssTransitions: boolean;
+}
+/**
+ * 检测宿主环境的能力
+ *
+ * @returns 宿主能力标志对象
+ * @example
+ * ```ts
+ * const caps = detectHostCapabilities()
+ * if (caps.shadowDOM) {
+ *   // 使用 Shadow DOM
+ * }
+ * ```
+ */
+declare function detectHostCapabilities(): HostCapabilities;
+/**
+ * 创建扩展宿主适配器的选项
+ */
+interface CreateExtendedHostOptions {
+    /** 基础宿主实现 */
+    baseHost: RendererHost;
+    /** 是否启用扩展的节点操作 */
+    enableExtendedNodeOps?: boolean;
+    /** 是否启用扩展的查询操作 */
+    enableExtendedQuery?: boolean;
+    /** 是否启用扩展的滚动操作 */
+    enableExtendedScroll?: boolean;
+}
+/**
+ * 为 Web DOM 环境创建扩展宿主适配器
+ *
+ * @param options - 创建选项
+ * @returns 扩展的宿主适配器
+ */
+declare function createExtendedWebHost(options: CreateExtendedHostOptions): ExtendedRendererHost<Node, Element>;
+declare function supportsHostCapability(capability: keyof HostCapabilities): boolean;
+/**
+ * 等待宿主环境就绪
+ *
+ * @returns Promise
+ */
+declare function waitForHostReady(): Promise<void>;
+
+/**
+ * @lytjs/adapter-web - Web Platform Adapter
+ * L3 Web 平台适配器，提供浏览器 DOM 的 RendererHost 实现。
+ *
+ * 所有 DOM API 调用集中在此包内，不泄漏到 L1/L2。
+ */
+
+/**
+ * 创建 Web 平台的 RendererHost 实例。
+ * 便捷工厂函数，等价于 `new WebRendererHost()`。
+ */
+declare function createWebHost(): RendererHost<Node, Element>;
+
+export { type CreateExtendedHostOptions, type DOMRenderer, type EventInvoker, type ExtendedRendererHost, type HostCapabilities, type HydrationRenderer, type ParsedEvent, WebRendererHost, createDOMRenderer, createExtendedWebHost, createHydrationFunctions, createInvoker, createWebHost, detectHostCapabilities, patchEvent, patchProp, removeAllEventListeners, supportsHostCapability, waitForHostReady, wrapDOMEvent };