@lytjs/component 6.7.0 → 6.8.0

package/dist/index.d.cts

@@ -0,0 +1,841 @@
+import { VNode } from '@lytjs/vdom';
+import { BaseAppContext, InternalSlots, ComponentPublicInstance, DebuggerEvent } from '@lytjs/shared-types';
+export { ComponentPublicInstance, InternalSlots, SlotFunction } from '@lytjs/shared-types';
+import { VNode as VNode$1 } from '@lytjs/common-vnode';
+import { ComputedSignal, Signal, EffectScope } from '@lytjs/reactivity';
+
+/** Prop 类型构造器 */
+type PropType<T> = {
+    new (...args: unknown[]): T & {};
+} | {
+    (): T;
+};
+type PropConstructor<T> = PropType<T> | true;
+interface PropOptions<T = unknown> {
+    type?: PropConstructor<T>;
+    required?: boolean;
+    default?: T;
+    validator?: (value: unknown) => boolean;
+}
+interface SetupContext {
+    attrs: Record<string, unknown>;
+    slots: InternalSlots;
+    emit: (event: string, ...args: unknown[]) => void;
+    expose?: (exposed?: Record<string, unknown>) => void;
+}
+type RenderFunction = (ctx: ComponentPublicInstance) => VNode;
+interface ComponentOptions<Props = Record<string, unknown>, RawBindings = Record<string, unknown>, D = Record<string, unknown>, C extends Record<string, unknown> = Record<string, unknown>> {
+    name?: string;
+    props?: Record<string, PropOptions<unknown>> & Props;
+    emits?: string[] | Record<string, (...args: unknown[]) => void>;
+    setup?: (props: Props, ctx: SetupContext) => RawBindings | RenderFunction | void;
+    render?: RenderFunction;
+    data?: () => D;
+    computed?: C;
+    watch?: Record<string, (...args: unknown[]) => void>;
+    methods?: Record<string, (...args: unknown[]) => unknown>;
+    provide?: Record<string, unknown> | (() => Record<string, unknown>);
+    inject?: Record<string, unknown>;
+    mixins?: ComponentOptions[];
+    extends?: ComponentOptions;
+    beforeCreate?(): void;
+    created?(): void;
+    beforeMount?(): void;
+    mounted?(): void;
+    beforeUpdate?(): void;
+    updated?(): void;
+    beforeUnmount?(): void;
+    unmounted?(): void;
+    activated?(): void;
+    deactivated?(): void;
+    errorCaptured?(err: Error, instance: ComponentPublicInstance | null, info: string): boolean | void;
+    renderTracked?(e: DebuggerEvent): void;
+    renderTriggered?(e: DebuggerEvent): void;
+    inheritAttrs?: boolean;
+}
+interface AppContextConfig {
+    /** 全局属性，可通过组件实例的 $ 访问 */
+    globalProperties?: Record<string, unknown>;
+    /** 全局错误处理器 */
+    errorHandler?: (err: Error, instance: unknown, info: string) => void;
+    /** 全局警告处理器 */
+    warnHandler?: (msg: string, instance: unknown, trace: string) => void;
+    /** 是否为原生标签 */
+    isNativeTag?: (tag: string) => boolean;
+    /** 自定义配置字段 */
+    [key: string]: unknown;
+}
+interface AppContext extends BaseAppContext<AppContextConfig> {
+    components: Record<string, ComponentOptions>;
+    directives: Record<string, unknown>;
+    mixins: ComponentOptions[];
+    provides: Record<string | symbol, unknown>;
+}
+/** 组件身份标识：type、name、uid 等 */
+interface ComponentIdentity {
+    uid: number;
+    type: ComponentOptions;
+}
+/** 组件生命周期状态：挂载/卸载标记、生命周期钩子等 */
+interface ComponentLifecycleState {
+    isMounted: boolean;
+    isUnmounted: boolean;
+    isDeactivated: boolean;
+    isKeepingAlive: boolean;
+    refs: Record<string, unknown>;
+    lifecycle: {
+        beforeMount: Set<(...args: unknown[]) => void>;
+        mounted: Set<(...args: unknown[]) => void>;
+        beforeUpdate: Set<(...args: unknown[]) => void>;
+        updated: Set<(...args: unknown[]) => void>;
+        beforeUnmount: Set<(...args: unknown[]) => void>;
+        unmounted: Set<(...args: unknown[]) => void>;
+    };
+    errorCapturedHooks?: Array<(err: Error, instance: ComponentPublicInstance | null, info: string) => boolean | void>;
+    activatedHooks?: Array<() => void>;
+    deactivatedHooks?: Array<() => void>;
+    renderTrackedHooks?: Array<(e: DebuggerEvent) => void>;
+    renderTriggeredHooks?: Array<(e: DebuggerEvent) => void>;
+}
+/** 组件渲染状态：render、subTree、update 等 */
+interface ComponentRenderState {
+    vnode: VNode | null;
+    subTree: VNode | null;
+    render?: RenderFunction;
+    effects?: Array<{
+        stop(): void;
+    }>;
+    update?: () => void;
+}
+/** 组件上下文状态：props、slots、attrs、emit、provides 等 */
+interface ComponentContextState {
+    props: Record<string, unknown>;
+    slots: InternalSlots;
+    ctx: ComponentPublicInstance;
+    setupState: Record<string, unknown>;
+    data: Record<string, unknown>;
+    propsOptions: Record<string, PropOptions>;
+    emitsOptions: Record<string, unknown> | null;
+    emit: (event: string, ...args: unknown[]) => void;
+    provides: Record<string | symbol, unknown>;
+    exposed?: Record<string, unknown> | null;
+    attrs: Record<string, unknown>;
+    accessCache: Record<string, number> | null;
+}
+/** 组件层级关系：parent、root、appContext 等 */
+interface ComponentParentState {
+    parent: ComponentInternalInstance | null;
+    root: ComponentInternalInstance;
+    appContext: AppContext;
+}
+interface ComponentInternalInstance extends ComponentIdentity, ComponentLifecycleState, ComponentRenderState, ComponentContextState, ComponentParentState {
+}
+
+/**
+ * 从 vnode 创建组件内部实例。
+ *
+ * 错误处理：实例创建包裹在 try-catch 中，防止
+ * 组件初始化期间的未捕获异常导致应用崩溃。
+ * 错误会传播到最近的 ErrorBoundary。
+ */
+declare function createComponentInstance(vnode: VNode$1, parent: ComponentInternalInstance | null): ComponentInternalInstance;
+/**
+ * 设置组件实例：运行 setup、初始化 props、初始化 slots。
+ */
+declare function setupComponent(instance: ComponentInternalInstance): void;
+/**
+ * 初始化并验证组件实例的 props。
+ */
+declare function initProps(instance: ComponentInternalInstance, rawProps: Record<string, unknown> | null): void;
+
+/**
+ * 完成组件 setup：处理 data、methods、computed、render。
+ *
+ * 错误处理：整个 setup 过程包裹在 try-catch 中，
+ * 优雅地处理 data/methods/computed/watch 初始化期间的错误。
+ * 错误会传播到最近的 ErrorBoundary。
+ */
+declare function finishComponentSetup(instance: ComponentInternalInstance): void;
+
+/**
+ * 公共属性名到 accessCache 位掩码的映射。
+ * 用于快速判断一个 key 是否是 Vue 内置公共属性（$data, $props 等）。
+ */
+declare const PUBLIC_PROPERTIES_MAP: Record<string, number>;
+/**
+ * Create the public instance proxy ($data, $props, $el, etc.).
+ * Uses a Proxy so that Options API `this` correctly resolves properties
+ * from setupState, data, props, and public instance fields ($el, $emit, etc.).
+ */
+declare function createComponentPublicInstance(instance: ComponentInternalInstance): ComponentPublicInstance;
+
+/**
+ * defineComponent 是一个恒等函数，直接返回选项对象。
+ * 它为组件选项提供 TypeScript 类型推断。
+ */
+declare function defineComponent(options: ComponentOptions): ComponentOptions;
+/**
+ * 定义函数式组件。
+ * 函数式组件没有实例、没有生命周期钩子、没有响应式状态。
+ * 它接收 props 并直接返回渲染函数。
+ *
+ * FIX: P1-22 使用精确类型替代 Record<string, any>，
+ * render 参数明确为返回 VNode 的函数，props 参数使用 Record<string, unknown>
+ */
+declare function defineFunctionalComponent(render: (props: Record<string, unknown>) => VNode$1 | VNode$1[] | null, props?: Record<string, unknown>): ComponentOptions;
+/**
+ * 创建基础应用上下文对象。
+ * 导出供 @lytjs/core 扩展运行时字段。
+ */
+declare function createAppContext(): AppContext;
+
+interface InjectionKey<T> {
+    /** 类型标志，用于类型推断，不运行时使用 */
+    __injectKey__?: T;
+}
+/**
+ * Inject 选项接口（改进版）
+ * 支持更精确的类型推断
+ */
+interface InjectOptions<T = unknown> {
+    /** 如果为 true，将 defaultValue 视为工厂函数，调用它来生成默认值 */
+    factory?: boolean;
+    /** 从特定的祖先 key 查找值，而非注入的 key */
+    from?: InjectionKey<T> | string | symbol;
+    /** 如果为 true，仅从当前实例自身的 provides 中查找值（不向上查找祖先） */
+    local?: boolean;
+}
+/**
+ * 向后代组件提供值。
+ * FIX: P1-9 COMPONENT-NEW-03 - 改进类型定义，支持 InjectionKey 类型推断
+ */
+declare function provide<T>(key: InjectionKey<T> | string | symbol, value: T): void;
+/**
+ * 从祖先组件注入值。
+ * FIX: P1-9 COMPONENT-NEW-03 - 改进类型定义，支持更精确的类型推断
+ *
+ * Supported forms:
+ * - `inject('key')` - basic lookup
+ * - `inject('key', defaultValue)` - with default value
+ * - `inject('key', () => createDefault(), { factory: true })` - factory function default
+ * - `inject('key', undefined, { from: 'optionalSourceKey' })` - from modifier
+ * - `inject('key', undefined, { local: true })` - local only (no ancestor lookup)
+ * - `inject(injectionKey)` - with InjectionKey for type-safe lookup
+ */
+declare function inject<T>(key: InjectionKey<T> | string | symbol, defaultValue?: T | (() => T), options?: InjectOptions<T>): T | undefined;
+
+/**
+ * 将 props 定义规范化为统一的 Record<string, PropOptions> 格式。
+ * 处理数组形式的 props（如 ['a', 'b']）和对象形式的 props。
+ */
+declare function normalizePropsOptions(rawProps?: Record<string, PropOptions> | string[]): Record<string, PropOptions>;
+/**
+ * 解析 prop 值，处理默认值和类型检查。
+ * 处理缺失 prop 的布尔类型转换。
+ */
+declare function resolvePropValue<T = unknown>(propOptions: PropOptions, value: unknown, _instance?: ComponentInternalInstance, key?: string): T | undefined;
+/**
+ * 根据类型或类型数组验证值。
+ */
+declare function validateType(value: unknown, type: unknown, key?: string): boolean;
+
+/**
+ * Normalize emits definition into a consistent Record<string, any> format.
+ */
+declare function normalizeEmitsOptions(emits?: string[] | Record<string, (...args: unknown[]) => unknown>): Record<string, unknown> | null;
+/**
+ * Emit an event on a component instance.
+ * Looks for `onXxx` handler in props and attrs (camelCase conversion).
+ */
+declare function emit(instance: ComponentInternalInstance, event: string, ...args: unknown[]): void;
+/**
+ * 检查事件是否在 emits 选项中声明。
+ * 使用与 emit() 相同的规范化（kebab-case -> camelCase）以确保
+ * 一致的事件名匹配。
+ */
+declare function isEmitValid(instance: ComponentInternalInstance, event: string): boolean;
+
+/**
+ * 从 children 初始化 slots。
+ * Children 可以是：
+ * - 插槽函数对象（命名插槽）
+ * - 单个函数（默认插槽）
+ * - null/undefined（无插槽）
+ *
+ * FIX: P2-20 动态 slot 缓存策略：
+ * slots 在初始化时被规范化并存储在 instance.slots 中。
+ * 如果需要动态更新 slots（如通过 scoped slots），应通过
+ * 组件更新机制触发重新初始化，而非直接修改 instance.slots。
+ */
+declare function initSlots(instance: ComponentInternalInstance, children: unknown): void;
+/**
+ * 将插槽返回值规范化为数组。
+ * 确保插槽函数始终返回数组，以保持渲染一致性。
+ */
+declare function normalizeSlotValue(value: unknown): VNode$1[];
+
+/**
+ * 设置当前实例（在 setup 期间使用）。
+ */
+declare function setCurrentInstance(instance: ComponentInternalInstance | null): void;
+/**
+ * 获取当前实例。
+ */
+declare function getCurrentInstance(): ComponentInternalInstance | null;
+/**
+ * 注册组件挂载完成后调用的回调。
+ */
+declare function onMounted(fn: () => void): void;
+/**
+ * 注册组件更新完成后调用的回调。
+ */
+declare function onUpdated(fn: () => void): void;
+/**
+ * 注册组件卸载后调用的回调。
+ */
+declare function onUnmounted(fn: () => void): void;
+/**
+ * Register a callback to be called before the component is mounted.
+ */
+declare function onBeforeMount(fn: () => void): void;
+/**
+ * 注册组件更新前调用的回调。
+ */
+declare function onBeforeUpdate(fn: () => void): void;
+/**
+ * 注册组件卸载前调用的回调。
+ */
+declare function onBeforeUnmount(fn: () => void): void;
+/**
+ * 注册错误捕获回调。
+ * 使用数组收集每个实例的多个回调。
+ */
+declare function onErrorCaptured(fn: (err: Error, instance: ComponentPublicInstance | null, info: string) => boolean | void): void;
+/**
+ * 注册组件被 KeepAlive 激活时调用的回调。
+ */
+declare function onActivated(fn: () => void): void;
+/**
+ * 注册组件被 KeepAlive 停用时调用的回调。
+ */
+declare function onDeactivated(fn: () => void): void;
+/**
+ * 注册渲染期间追踪响应式依赖时调用的回调。
+ * 仅在开发模式下生效。
+ */
+declare function onRenderTracked(fn: (e: DebuggerEvent) => void): void;
+/**
+ * 注册渲染期间触发响应式依赖时调用的回调。
+ * 仅在开发模式下生效。
+ */
+declare function onRenderTriggered(fn: (e: DebuggerEvent) => void): void;
+/**
+ * Call all registered hooks for a given lifecycle phase.
+ */
+declare function callLifecycleHook(instance: ComponentInternalInstance, hookName: 'beforeMount' | 'mounted' | 'beforeUpdate' | 'updated' | 'beforeUnmount' | 'unmounted'): void;
+/**
+ * 调用 beforeCreate 和 created 生命周期钩子（选项式 API）。
+ */
+declare function callCreatedHook(instance: ComponentInternalInstance): void;
+/**
+ * 调用 beforeMount 和 mounted 生命周期钩子（选项式 API）。
+ */
+declare function callMountedHook(instance: ComponentInternalInstance): void;
+/**
+ * 调用 beforeUpdate 和 updated 生命周期钩子（选项式 API）。
+ */
+declare function callUpdatedHook(instance: ComponentInternalInstance): void;
+/**
+ * 调用 beforeUnmount 和 unmounted 生命周期钩子（选项式 API）。
+ */
+declare function callUnmountedHook(instance: ComponentInternalInstance): void;
+/**
+ * 处理错误捕获传播。
+ * 调用当前实例上所有通过 onErrorCaptured() 注册的 errorCapturedHooks（从内到外），
+ * 然后传播到父组件。如果错误被处理则返回 true。
+ */
+declare function handleError(err: Error, instance: ComponentInternalInstance | null, info: string): boolean;
+
+interface KeepAliveProps {
+    include?: string | RegExp | (string | RegExp)[];
+    exclude?: string | RegExp | (string | RegExp)[];
+    /** FIX: P2-17 缓存大小限制配置（默认 10） */
+    max?: number;
+    /** 自定义缓存 key 函数：接收一个 vnode，返回字符串或数字作为缓存 key */
+    onCacheKey?: (vnode: VNode) => string | number;
+}
+declare const KeepAlive: ComponentOptions;
+/**
+ * 创建 KeepAlive 组件实例。
+ */
+declare function createKeepAliveInstance(props?: KeepAliveProps, parent?: ComponentInternalInstance | null): ComponentInternalInstance;
+/**
+ * 检查组件名是否匹配 include/exclude 模式。
+ */
+declare function matchesPattern(name: string | undefined, pattern: string | RegExp | (string | RegExp)[] | undefined): boolean;
+/**
+ * 获取 KeepAlive 上下文中 vnode 的缓存 key。
+ *
+ * 如果 KeepAlive 实例有 `onCacheKey` prop（自定义函数），
+ * 则使用该函数计算缓存 key。
+ * 否则，默认 key 从 `vnode.type`（组件构造函数或标签名）派生。
+ *
+ * @param keepAlive - KeepAlive 组件实例
+ * @param vnode - 需要计算缓存 key 的 vnode
+ * @returns 字符串形式的缓存 key
+ */
+declare function getCacheKey(keepAlive: ComponentInternalInstance, vnode: VNode): string;
+/**
+ * 在 KeepAlive 中缓存组件实例。
+ * FIX: P2-8 COMPONENT-NEW-05 - LRU 缓存自动处理容量限制
+ */
+declare function cacheInstance(keepAlive: ComponentInternalInstance, key: string, instance: ComponentInternalInstance): void;
+/**
+ * Get a cached instance from KeepAlive.
+ */
+declare function getCachedInstance(keepAlive: ComponentInternalInstance, key: string): ComponentInternalInstance | undefined;
+/**
+ * 从 KeepAlive 移除缓存的实例。
+ */
+declare function removeCachedInstance(keepAlive: ComponentInternalInstance, key: string): boolean;
+/**
+ * 激活缓存的组件实例。
+ */
+declare function activateInstance(instance: ComponentInternalInstance): void;
+/**
+ * 停用组件实例。
+ */
+declare function deactivateInstance(instance: ComponentInternalInstance): void;
+
+interface SuspenseProps {
+    timeout?: number;
+    onResolve?: () => void;
+    onPending?: () => void;
+    onError?: (error: Error) => void;
+}
+interface SuspenseAsyncState {
+    isPending: boolean;
+    error: Error | null;
+    /** @deprecated 使用 pendingPromises 代替 */
+    promise: Promise<unknown> | null;
+    pendingPromises: Set<Promise<unknown>>;
+    onResolve: (() => void)[];
+    onPending: (() => void)[];
+    onError: ((error: Error) => void)[];
+    aborted: boolean;
+    /**
+     * 关联的 vdom 层 SuspenseBoundary 引用。
+     * 当异步状态变化时，通过此引用驱动 DOM 切换。
+     */
+    vnodeBoundary?: {
+        vnode: VNode$1;
+        container: unknown;
+        anchor: unknown;
+        parentComponent: ComponentInternalInstance | null;
+        isSVG: boolean;
+        isInFallback: boolean;
+        activeBranch: VNode$1 | null;
+        pendingBranch: VNode$1 | null;
+    };
+    /**
+     * DOM 切换函数，由 vdom 层的 patch 函数提供。
+     * 用于在 pending/resolve 状态变化时执行实际的 DOM 操作。
+     */
+    domSwitch?: (boundary: SuspenseAsyncState, toFallback: boolean) => void;
+}
+declare const Suspense: ComponentOptions;
+/**
+ * 创建 Suspense 组件实例。
+ */
+declare function createSuspenseInstance(props?: SuspenseProps, parent?: ComponentInternalInstance | null): ComponentInternalInstance;
+/**
+ * 创建 suspense boundary 用于管理异步子组件。
+ */
+declare function createSuspenseBoundary(): SuspenseAsyncState;
+/**
+ * Register an async child with the suspense boundary.
+ * Returns true if this is the first pending child (transition to pending).
+ */
+declare function registerAsyncChild(boundary: SuspenseAsyncState, promise: Promise<unknown>): boolean;
+/**
+ * 检查 suspense boundary 当前是否处于 pending 状态。
+ */
+declare function isSuspensePending(boundary: SuspenseAsyncState): boolean;
+/**
+ * Get the error from a suspense boundary (if any).
+ */
+declare function getSuspenseError(boundary: SuspenseAsyncState): Error | null;
+/**
+ * 将 vdom 层的 SuspenseBoundary 与 component 层的 SuspenseAsyncState 关联。
+ * 由 vdom 的 mountSuspense 调用，使异步状态变化能驱动 DOM 切换。
+ */
+declare function linkSuspenseBoundary(asyncState: SuspenseAsyncState, vnodeBoundary: SuspenseAsyncState['vnodeBoundary'], domSwitch: SuspenseAsyncState['domSwitch']): void;
+/**
+ * 手动解决 suspense boundary。
+ *
+ * FIX: P1-20 添加语义注释：
+ * resolveSuspense 用于手动将 suspense 边界标记为已解决状态。
+ * 调用后，所有 pending 的 Promise 将被忽略（通过设置 aborted = true），
+ * onResolve 回调将被触发，DOM 将从 fallback 切回默认内容。
+ * 注意：此方法不会等待正在进行的异步操作完成，而是立即强制解决。
+ * 适用场景：用户手动取消等待、路由切换等需要立即恢复的场景。
+ */
+declare function resolveSuspense(boundary: SuspenseAsyncState): void;
+/**
+ * 中止 suspense boundary（例如在卸载时）。
+ * 拒绝所有 pending 的 Promise 以防止内存泄漏，并允许
+ * 下游消费者通过 .catch() 处理中止。
+ *
+ * FIX: P1-20 添加语义注释：
+ * abortSuspense 用于在组件卸载等场景下中止 suspense 边界。
+ * 与 resolveSuspense 不同，abortSuspense 不会触发 onResolve 回调，
+ * 而是清空所有回调数组以防止后续调用。所有 pending 的 Promise
+ * 将尝试通过 abort 方法取消（如果是自定义 thenable）。
+ * 适用场景：组件卸载、路由切换导致组件树销毁等。
+ */
+declare function abortSuspense(boundary: SuspenseAsyncState): void;
+/**
+ * useSuspense Hook
+ * 将 Promise 注册到当前 Suspense 边界
+ */
+declare function useSuspense<T>(promise: Promise<T>, _key?: string): T;
+/**
+ * startTransition 函数
+ * 标记更新为过渡更新，不会立即触发 Suspense fallback
+ */
+declare function startTransition(callback: () => void): void;
+/**
+ * SuspenseResource 类
+ * 用于管理可缓存的异步资源
+ */
+declare class SuspenseResource<T> {
+    private status;
+    private value;
+    private error;
+    private promise;
+    constructor(factory: () => Promise<T>);
+    private load;
+    read(): T;
+    refresh(factory: () => Promise<T>): void;
+}
+/**
+ * 创建 Suspense 资源
+ */
+declare function createSuspenseResource<T>(factory: () => Promise<T>): SuspenseResource<T>;
+
+/**
+ * Transition 组件属性（泛型版本）。
+ * @template HE - 宿主元素类型
+ */
+interface TransitionComponentProps<HE = unknown> {
+    name?: string;
+    appear?: boolean;
+    mode?: 'in-out' | 'out-in' | 'default';
+    enterFromClass?: string;
+    enterActiveClass?: string;
+    enterToClass?: string;
+    leaveFromClass?: string;
+    leaveActiveClass?: string;
+    leaveToClass?: string;
+    onBeforeEnter?: (el: HE) => void;
+    onEnter?: (el: HE, done: () => void) => void;
+    onAfterEnter?: (el: HE) => void;
+    onEnterCancelled?: (el: HE) => void;
+    onBeforeLeave?: (el: HE) => void;
+    onLeave?: (el: HE, done: () => void) => void;
+    onAfterLeave?: (el: HE) => void;
+    onLeaveCancelled?: (el: HE) => void;
+}
+/**
+ * @deprecated 使用 TransitionComponentProps<HE> 代替。
+ * 保留此类型别名以确保向后兼容。
+ */
+type TransitionComponentPropsLegacy = TransitionComponentProps<Element>;
+declare const Transition: ComponentOptions;
+
+/**
+ * TransitionGroup 组件属性（泛型版本）。
+ * @template HE - 宿主元素类型
+ */
+interface TransitionGroupComponentProps<HE = unknown> {
+    name?: string;
+    appear?: boolean;
+    tag?: string | false;
+    moveClass?: string;
+    enterFromClass?: string;
+    enterActiveClass?: string;
+    enterToClass?: string;
+    leaveFromClass?: string;
+    leaveActiveClass?: string;
+    leaveToClass?: string;
+    onBeforeEnter?: (el: HE) => void;
+    onEnter?: (el: HE, done: () => void) => void;
+    onAfterEnter?: (el: HE) => void;
+    onEnterCancelled?: (el: HE) => void;
+    onBeforeLeave?: (el: HE) => void;
+    onLeave?: (el: HE, done: () => void) => void;
+    onAfterLeave?: (el: HE) => void;
+    onLeaveCancelled?: (el: HE) => void;
+}
+/**
+ * @deprecated 使用 TransitionGroupComponentProps<HE> 代替。
+ * 保留此类型别名以确保向后兼容。
+ */
+type TransitionGroupComponentPropsLegacy = TransitionGroupComponentProps<Element>;
+declare const TransitionGroup: ComponentOptions;
+
+interface TeleportProps {
+    to: string | Element;
+    disabled?: boolean;
+}
+declare const Teleport: ComponentOptions;
+
+interface ErrorBoundaryProps {
+    onError?: (error: Error, info: string) => void;
+    fallback?: ComponentOptions;
+}
+declare const ErrorBoundary: ComponentOptions;
+
+/**
+ * 创建与组件协作的 Signal State
+ */
+declare function createSignalState<T>(initialValue: T): Signal<T>;
+/**
+ * 创建与组件协作的 Computed Signal State
+ */
+declare function createComputedState<T>(getter: () => T): ComputedSignal<T>;
+
+/**
+ * 异步组件加载器函数类型
+ */
+type AsyncComponentLoader<T = unknown> = () => Promise<T>;
+/**
+ * 定义异步组件的选项
+ */
+interface AsyncComponentOptions {
+    /**
+     * 返回 Promise 解析为组件的加载器函数
+     */
+    loader: AsyncComponentLoader<ComponentOptions>;
+    /**
+     * 异步组件加载时显示的组件
+     */
+    loadingComponent?: ComponentOptions;
+    /**
+     * 异步组件加载失败时显示的组件
+     */
+    errorComponent?: ComponentOptions;
+    /**
+     * 显示加载组件前的延迟时间（毫秒）
+     * @default 200
+     */
+    delay?: number;
+    /**
+     * 异步组件加载的超时时间（毫秒）
+     */
+    timeout?: number;
+    /**
+     * 是否挂起组件渲染直到加载完成
+     * @default false
+     */
+    suspensible?: boolean;
+    /**
+     * 异步组件加载失败时的错误处理器
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * 异步组件加载的内部状态
+ */
+interface AsyncComponentState {
+    loadedComponent: ComponentOptions | null;
+    error: Error | null;
+    isLoading: boolean;
+    isLoaded: boolean;
+    isError: boolean;
+    loadingPromise: Promise<void> | null;
+}
+/**
+ * 定义一个异步组件，支持加载、错误和预加载功能。
+ *
+ * @example
+ * ```ts
+ * const AsyncComp = defineAsyncComponent({
+ *   loader: () => import('./MyComponent.vue'),
+ *   loadingComponent: LoadingSpinner,
+ *   errorComponent: ErrorDisplay,
+ *   delay: 200,
+ *   timeout: 3000,
+ * });
+ *
+ * // Preload the component before it's needed
+ * AsyncComp.preload();
+ * ```
+ */
+declare function defineAsyncComponent(options: AsyncComponentOptions | AsyncComponentLoader<ComponentOptions>): ComponentOptions & {
+    preload: () => Promise<void>;
+};
+/**
+ * 一次性预加载多个异步组件。
+ *
+ * @example
+ * ```ts
+ * preloadComponents([
+ *   () => import('./CompA.vue'),
+ *   () => import('./CompB.vue'),
+ *   () => import('./CompC.vue'),
+ * ]);
+ * ```
+ */
+declare function preloadComponents(loaders: AsyncComponentLoader[]): Promise<void>;
+/**
+ * 通过加载器函数预加载单个组件。
+ */
+declare function preloadComponent(loader: AsyncComponentLoader): Promise<void>;
+/**
+ * 检查组件是否已被预加载。
+ */
+declare function isComponentPreloaded(loader: AsyncComponentLoader): boolean;
+/**
+ * 清除特定加载器或所有加载器的预加载缓存。
+ */
+declare function clearPreloadCache(loader?: AsyncComponentLoader): void;
+
+/**
+ * InjectionToken - 类型安全的注入令牌
+ *
+ * 与 InjectionKey 不同，InjectionToken 是一个类实例，
+ * 可以携带更多元数据（如描述、工厂函数、生命周期等）
+ *
+ * @example
+ * ```ts
+ * const API_URL = new InjectionToken<string>('api-url');
+ * const Database = new InjectionToken<Database>('database', {
+ *   factory: () => new Database(),
+ *   lifecycle: 'singleton',
+ * });
+ * ```
+ */
+declare class InjectionToken<T> {
+    /** 令牌描述 */
+    readonly description: string;
+    /** 令牌唯一标识 */
+    readonly __token: symbol;
+    /** 工厂函数 */
+    readonly factory?: () => T;
+    /** 生命周期 */
+    readonly lifecycle?: ProviderLifecycle;
+    constructor(description: string, options?: {
+        factory?: () => T;
+        lifecycle?: ProviderLifecycle;
+    });
+    toString(): string;
+}
+/**
+ * 判断是否是 InjectionToken
+ */
+declare function isInjectionToken(value: unknown): value is InjectionToken<unknown>;
+/** Provider 生命周期类型 */
+type ProviderLifecycle = 'singleton' | 'scoped' | 'transient';
+/** Provider 配置 */
+interface ProviderConfig<T = unknown> {
+    /** 提供的值 */
+    provide?: T;
+    /** 工厂函数 */
+    useFactory?: () => T;
+    /** 现有令牌别名 */
+    useExisting?: InjectionToken<T> | string | symbol;
+    /** 生命周期 */
+    lifecycle?: ProviderLifecycle;
+    /** 是否可选 */
+    optional?: boolean;
+}
+/** Provider 记录 */
+interface ProviderRecord {
+    value: unknown;
+    lifecycle: ProviderLifecycle;
+    scope?: EffectScope;
+    instanceId?: symbol;
+}
+/**
+ * Provider 树节点
+ * 支持嵌套的 Provider 层级结构
+ */
+interface ProviderNode {
+    /** 唯一标识 */
+    id: symbol;
+    /** 父节点 */
+    parent: ProviderNode | null;
+    /** 子节点 */
+    children: Set<ProviderNode>;
+    /** 提供的值 */
+    providers: Map<string | symbol, ProviderRecord>;
+    /** 作用域 */
+    scope: EffectScope;
+}
+/**
+ * 获取或创建全局 Provider 根节点
+ */
+declare function getProviderRoot(): ProviderNode;
+/**
+ * 进入新的 Provider 作用域
+ */
+declare function enterProviderScope(): ProviderNode;
+/**
+ * 退出当前 Provider 作用域
+ */
+declare function exitProviderScope(): void;
+/**
+ * 获取当前 Provider 节点
+ */
+declare function getCurrentProviderNode(): ProviderNode | null;
+/**
+ * 增强的 Inject 选项
+ */
+interface EnhancedInjectOptions<T = unknown> {
+    /** 是否可选（找不到时不报错） */
+    optional?: boolean;
+    /** 默认值 */
+    default?: T | (() => T);
+    /** 从特定祖先查找 */
+    from?: InjectionToken<T> | string | symbol;
+    /** 是否仅查找当前层级 */
+    local?: boolean;
+    /** 是否跳过自身（仅查找祖先） */
+    skipSelf?: boolean;
+}
+/**
+ * 注入错误
+ */
+declare class InjectionError extends Error {
+    token: string | symbol;
+    constructor(token: string | symbol, message: string);
+}
+/**
+ * 创建并注册一个单例 Provider
+ */
+declare function provideSingleton<T>(key: InjectionToken<T> | string | symbol, factory: () => T): void;
+/**
+ * 创建并注册一个作用域 Provider
+ */
+declare function provideScoped<T>(key: InjectionToken<T> | string | symbol, factory: () => T): void;
+/**
+ * 创建并注册一个临时 Provider
+ */
+declare function provideTransient<T>(key: InjectionToken<T> | string | symbol, factory: () => T): void;
+/**
+ * 批量注册 Providers
+ */
+declare function provideAll(providers: Array<{
+    provide: InjectionToken<unknown> | string | symbol;
+    useValue?: unknown;
+    useFactory?: () => unknown;
+    useExisting?: InjectionToken<unknown> | string | symbol;
+    lifecycle?: ProviderLifecycle;
+}>): void;
+/**
+ * 创建一个 Provider 作用域并执行回调
+ */
+declare function withProviderScope<T>(fn: () => T): T;
+
+export { type AppContext, type AsyncComponentLoader, type AsyncComponentOptions, type AsyncComponentState, type ComponentContextState, type ComponentIdentity, type ComponentInternalInstance, type ComponentLifecycleState, type ComponentOptions, type ComponentParentState, type ComponentRenderState, type EnhancedInjectOptions, ErrorBoundary, type ErrorBoundaryProps, type InjectOptions, InjectionError, InjectionToken, KeepAlive, type KeepAliveProps, PUBLIC_PROPERTIES_MAP, type PropOptions, type PropType, type ProviderConfig, type ProviderLifecycle, type ProviderNode, type RenderFunction, type SetupContext, Suspense, type SuspenseAsyncState, type SuspenseProps, SuspenseResource, Teleport, type TeleportProps, Transition, type TransitionComponentProps, type TransitionComponentPropsLegacy, TransitionGroup, type TransitionGroupComponentProps, type TransitionGroupComponentPropsLegacy, abortSuspense, activateInstance, cacheInstance, callCreatedHook, callLifecycleHook, callMountedHook, callUnmountedHook, callUpdatedHook, clearPreloadCache, createAppContext, createComponentInstance, createComponentPublicInstance, createComputedState, createKeepAliveInstance, createSignalState, createSuspenseBoundary, createSuspenseInstance, createSuspenseResource, deactivateInstance, defineAsyncComponent, defineComponent, defineFunctionalComponent, emit, enterProviderScope, exitProviderScope, finishComponentSetup, getCacheKey, getCachedInstance, getCurrentInstance, getCurrentProviderNode, getProviderRoot, getSuspenseError, handleError, initProps, initSlots, inject, isComponentPreloaded, isEmitValid, isInjectionToken, isSuspensePending, linkSuspenseBoundary, matchesPattern, normalizeEmitsOptions, normalizePropsOptions, normalizeSlotValue, onActivated, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onDeactivated, onErrorCaptured, onMounted, onRenderTracked, onRenderTriggered, onUnmounted, onUpdated, preloadComponent, preloadComponents, provide, provideAll, provideScoped, provideSingleton, provideTransient, registerAsyncChild, removeCachedInstance, resolvePropValue, resolveSuspense, setCurrentInstance, setupComponent, startTransition, useSuspense, validateType, withProviderScope };