@vitarx/plugin-vite 0.0.1-alpha.0 → 0.0.1-alpha.1

package/dist/components.d.ts

@@ -0,0 +1,86 @@
+import type { RenderUnit, View } from 'vitarx';
+interface IfBlockProps {
+    /**
+     * 子元素列表
+     *
+     * 所有子元素必须带有 v-if / v-else-if / v-else 指令，且组合顺序必须正确！
+     */
+    children: View[];
+}
+interface SwitchProps {
+    /**
+     * 默认渲染内容
+     *
+     * 当所有 `Match` 都不匹配时，渲染该内容
+     */
+    fallback?: RenderUnit;
+    /**
+     * 子元素列表
+     *
+     * 必须是 `Match` 组件
+     */
+    children: View | View[];
+}
+interface MatchProps {
+    /**
+     * 匹配条件
+     */
+    when: unknown;
+    /**
+     * 匹配成功时渲染的内容
+     */
+    children: RenderUnit;
+}
+declare global {
+    /**
+     * IfBlock - 编译宏组件，无需import导入
+     *
+     * IfBlock 组件不具有运行时效果，它只是为了兼容tsx类型校验，
+     * 例如 `<Comp><h1 v-if={cond} /><h2 v-else /><Comp>`，Comp组件的children要求传入单个元素时tsx类型会误报，使用 `IfBlock` 包裹则可以使 v-if 组合链通过 children 类型校验
+     *
+     * @example
+     * ```tsx
+     * import { View } from 'vitarx';
+     * function TestComp(props:{children:View}) {
+     *   return <div>{props.children}</div>
+     * }
+     * function App() {
+     *   return (
+     *    <TestComp>
+     *       <IfBlock>
+     *          <h1 v-if={cond}/>
+     *          <h2 v-else/>
+     *       </IfBlock>
+     *    </TestComp>
+     *   )
+     * }
+     * ```
+     */
+    const IfBlock: (props: IfBlockProps) => View;
+    /**
+     * Switch - 编译宏组件，无需import导入
+     *
+     * Switch 组件用于条件渲染，`Match` 是其唯一合法子元素，
+     * 通过 `when` 属性判断是否匹配，匹配则渲染 `Match` 子元素，否则渲染 `fallback`
+     *
+     * @example
+     * ```tsx
+     * function App() {
+     *   return (
+     *    <Switch fallback="Default">
+     *       <Match when={a}>A</Match>
+     *       <Match when={b}>B</Match>
+     *    </Switch>
+     *   )
+     * }
+     * ```
+     */
+    const Switch: (props: SwitchProps) => View;
+    /**
+     * Match - 编译宏组件，无需import导入
+     *
+     * 需 `Switch` 组件搭配使用，不允许单独使用。
+     */
+    const Match: (props: MatchProps) => View;
+}
+export {};

package/dist/constants/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Vitarx 运行时 API 名称
+ * 这些 API 需要从 vitarx 包导入
+ */
+export declare const VITARX_APIS: {
+    readonly CREATE_VIEW: "createView";
+    readonly FRAGMENT: "Fragment";
+    readonly BRANCH: "branch";
+    readonly DYNAMIC: "dynamic";
+    readonly ACCESS: "access";
+    readonly WITH_DIRECTIVES: "withDirectives";
+    readonly UNREF: "unref";
+    readonly IS_REF: "isRef";
+};
+/**
+ * Ref 相关 API 名称
+ * 用于识别 ref 变量
+ */
+export declare const REF_APIS: {
+    readonly REF: "ref";
+    readonly TO_REF: "toRef";
+    readonly TO_REFS: "toRefs";
+    readonly SHALLOW_REF: "shallowRef";
+    readonly COMPUTED: "computed";
+};
+/**
+ * 支持的响应式模块
+ * 从这些模块导入的 ref API 会被识别
+ */
+export declare const RESPONSIVE_MODULES: readonly ["vitarx", "@vitarx/responsive"];
+/**
+ * 纯编译组件名称
+ * 这些组件在编译时会被完全转换
+ */
+export declare const PURE_COMPILE_COMPONENTS: readonly ["Switch", "Match", "IfBlock"];
+/**
+ * 指令前缀
+ */
+export declare const DIRECTIVE_PREFIX = "v-";
+/**
+ * 纯函数注释
+ */
+export declare const PURE_COMMENT = "@__PURE__";
+/**
+ * vitarx 模块名称
+ */
+export declare const VITARX_MODULE = "vitarx";
+/**
+ * 标识符
+ */
+export declare enum HMR {
+    manager = "__$VITARX_HMR$__",
+    id = "__$VITARX_HMR_COMPONENT_ID$__",
+    view = "__$VITARX_HMR_VIEW_NODE$__",
+    state = "__$VITARX_HMR_VIEW_STATE$__"
+}
+/** 默认导出组件基础名称 */
+export declare const DEFAULT_EXPORT_BASE_NAME = "_defaultExport";

package/dist/context.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 转换上下文模块
+ * 定义编译转换过程中的上下文数据结构
+ * @module context
+ */
+import type { File } from '@babel/types';
+import type { CompileOptions } from './transform.js';
+import type { CompilerWarning } from './error.js';
+/**
+ * UI 相关的 API 名称列表
+ * 这些 API 用于创建视图，在 HMR 时需要识别
+ */
+export declare const UI_API_NAMES: readonly ["createView", "branch", "dynamic", "access", "withDirectives"];
+export type UIApiName = (typeof UI_API_NAMES)[number];
+/**
+ * 导入信息
+ * 追踪需要注入的运行时 API
+ */
+export interface ImportInfo {
+    /** createView - 视图创建函数 */
+    createView: boolean;
+    /** Fragment - 片段组件 */
+    Fragment: boolean;
+    /** branch - 条件分支函数 */
+    branch: boolean;
+    /** dynamic - 动态值包装函数 */
+    dynamic: boolean;
+    /** access - 属性访问函数 */
+    access: boolean;
+    /** withDirectives - 指令包装函数 */
+    withDirectives: boolean;
+    /** unref - ref 解包函数 */
+    unref: boolean;
+    /** isRef - ref 类型检查函数 */
+    isRef: boolean;
+}
+/**
+ * Vitarx 导入别名映射
+ * 记录运行时 API 的本地别名
+ */
+export interface VitarxImportAliases {
+    createView: string | null;
+    Fragment: string | null;
+    branch: string | null;
+    dynamic: string | null;
+    access: string | null;
+    withDirectives: string | null;
+    unref: string | null;
+    isRef: string | null;
+}
+/**
+ * Ref API 别名映射
+ * 记录响应式 API 的本地别名
+ */
+export interface RefApiAliases {
+    ref: string | null;
+    toRef: string | null;
+    toRefs: string | null;
+    shallowRef: string | null;
+    computed: string | null;
+}
+/**
+ * 转换上下文
+ * 包含编译过程中需要的所有状态信息
+ */
+export interface TransformContext {
+    /** 原始源代码 */
+    code: string;
+    /** 文件标识符（可能包含查询参数） */
+    id: string;
+    /** 文件名（不含查询参数） */
+    filename: string;
+    /** 编译选项 */
+    options: CompileOptions;
+    /** 解析后的 AST */
+    ast: File;
+    /** 需要注入的导入信息 */
+    imports: ImportInfo;
+    /** 已存在的导入名称集合 */
+    existingImports: Set<string>;
+    /** Vitarx API 别名映射 */
+    vitarxAliases: VitarxImportAliases;
+    /** Ref API 别名映射 */
+    refApiAliases: RefApiAliases;
+    /** ref 变量名集合 */
+    refVariables: Set<string>;
+    /** UI API 别名集合（用于 HMR 代码分离识别） */
+    uiApiAliases: Set<string>;
+    /** 编译警告列表 */
+    warnings: CompilerWarning[];
+}
+/**
+ * 创建转换上下文
+ * @param code - 源代码
+ * @param id - 文件标识符
+ * @param options - 编译选项
+ * @param ast - AST 节点
+ * @returns 转换上下文对象
+ */
+export declare function createContext(code: string, id: string, options: CompileOptions, ast: File): TransformContext;
+/**
+ * 标记需要注入的导入
+ * @param ctx - 转换上下文
+ * @param name - 导入名称
+ */
+export declare function markImport(ctx: TransformContext, name: keyof ImportInfo): void;
+/**
+ * 记录 UI API 别名
+ * @param ctx - 转换上下文
+ * @param alias - API 别名
+ */
+export declare function markUiApiAlias(ctx: TransformContext, alias: string): void;
+/**
+ * 添加编译警告
+ * @param ctx - 转换上下文
+ * @param warning - 编译警告
+ */
+export declare function addWarning(ctx: TransformContext, warning: CompilerWarning): void;

package/dist/error.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 编译错误处理模块
+ * 定义编译器错误类型和错误消息
+ * @module error
+ */
+import type { Node } from '@babel/types';
+/**
+ * 错误位置信息
+ */
+export interface ErrorLocation {
+    /** 行号 */
+    line: number;
+    /** 列号 */
+    column: number;
+}
+/**
+ * 编译错误选项
+ */
+export interface CompilerErrorOptions {
+    /** 错误代码 */
+    code: string;
+    /** 错误消息 */
+    message: string;
+    /** 错误位置 */
+    loc?: ErrorLocation;
+    /** 相关 AST 节点 */
+    node?: Node;
+}
+/**
+ * 编译器错误类
+ * 包含错误代码和位置信息
+ */
+export declare class CompilerError extends Error {
+    /** 错误代码 */
+    code: string;
+    /** 错误位置 */
+    loc?: ErrorLocation;
+    constructor(options: CompilerErrorOptions);
+}
+/**
+ * 错误代码枚举
+ */
+export declare const ErrorCodes: {
+    /** 不能同时使用展开属性和 v-bind */
+    readonly E001: "E001";
+    /** 重复的展开属性或属性键 */
+    readonly E002: "E002";
+    /** v-else 没有前置的 v-if */
+    readonly E003: "E003";
+    /** v-else-if 没有前置的 v-if */
+    readonly E004: "E004";
+    /** v-if 链不连续 */
+    readonly E005: "E005";
+    /** Switch 组件有无效子节点 */
+    readonly E006: "E006";
+    /** Match 组件缺少 when 属性 */
+    readonly E007: "E007";
+    /** IfBlock 有无效子元素 */
+    readonly E008: "E008";
+    /** v-model 与 modelValue 或 onUpdate:modelValue 冲突 */
+    readonly E009: "E009";
+    /** v-model 值必须是 Identifier 或 MemberExpression */
+    readonly E010: "E010";
+    /** v-model Identifier 必须是 ref */
+    readonly E011: "E011";
+    /** Match 组件必须在 Switch 内使用 */
+    readonly E012: "E012";
+    /** Match 组件必须有子元素 */
+    readonly E013: "E013";
+    /** IfBlock 组件必须有子元素 */
+    readonly E014: "E014";
+    /** Switch 组件必须有 Match 子元素 */
+    readonly E015: "E015";
+};
+/**
+ * 警告代码枚举
+ */
+export declare const WarningCodes: {
+    /** children 属性和子元素同时存在 */
+    readonly W001: "W001";
+};
+/**
+ * 错误消息映射
+ */
+export declare const ErrorMessages: Record<string, string>;
+/**
+ * 警告消息映射
+ */
+export declare const WarningMessages: Record<string, string>;
+/**
+ * 创建编译错误
+ * @param code - 错误代码
+ * @param node - 相关 AST 节点
+ * @param additionalMessage - 附加消息
+ * @returns 编译错误实例
+ */
+export declare function createError(code: keyof typeof ErrorCodes, node?: Node, additionalMessage?: string): CompilerError;
+/**
+ * 编译警告类
+ */
+export declare class CompilerWarning {
+    /** 警告代码 */
+    code: string;
+    /** 警告消息 */
+    message: string;
+    /** 警告位置 */
+    loc?: ErrorLocation;
+    constructor(code: string, message: string, loc?: ErrorLocation);
+    toString(): string;
+}
+/**
+ * 创建编译警告
+ * @param code - 警告代码
+ * @param node - 相关 AST 节点
+ * @returns 编译警告实例
+ */
+export declare function createWarning(code: keyof typeof WarningCodes, node?: Node): CompilerWarning;

package/dist/hmr-client/index.d.ts

@@ -0,0 +1,56 @@
+import { Component, ComponentView } from 'vitarx';
+import type { ModuleNamespace } from 'vite/types/hot.js';
+import { HMR } from '../constants/index.js';
+declare global {
+    interface Window {
+        [HMR.manager]: HMRManager;
+    }
+}
+declare module 'vitarx' {
+    interface ComponentView {
+        [HMR.state]?: Record<string, any>;
+    }
+}
+export default class HMRManager {
+    #private;
+    /**
+     * 获取单实例
+     */
+    static get instance(): HMRManager;
+    /**
+     * 给组件绑定唯一id
+     *
+     * @param component
+     * @param id
+     */
+    bindId(component: Function, id: string): void;
+    /**
+     * 置换新模块
+     *
+     * 此方法提供给`jsxDev`函数调用，保持每次创建组件实例都是最新的模块！
+     * @param component
+     */
+    resolveComponent(component: Component): Component;
+    /**
+     * 恢复状态
+     *
+     * @param {ComponentView} view - 组件视图
+     * @param {string} name - 变量名称
+     * @example
+     * const state = __$VITARX_HMR$__.instance.memo(__$VITARX_HMR_VIEW_NODE$__, 'state') ?? ref(0)
+     */
+    memo(view: ComponentView, name: string): any;
+    /**
+     * 注册节点
+     *
+     * @param view - 组件视图节点
+     */
+    register(view: ComponentView): void;
+    /**
+     * 获取模块id
+     *
+     * @param component
+     */
+    getId(component: Component): string;
+    update(mod: ModuleNamespace): void;
+}

package/dist/hmr-client/update.d.ts

@@ -0,0 +1,7 @@
+import { Component, ComponentView } from 'vitarx';
+/**
+ * 处理组件更新函数
+ * @param view - 组件视图对象，包含当前组件的实例和节点信息
+ * @param newComponent - 新的组件定义，用于替换现有组件
+ */
+export declare function processUpdate(view: ComponentView, newComponent: Component): void;

package/dist/hmr-client/utils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 代码变更类型
+ */
+export interface ChangeCode {
+    /** UI 描述代码是否变化（需要重新构建视图） */
+    build: boolean;
+    /** 非 UI 代码是否变化（需要完全重新挂载） */
+    logic: boolean;
+}
+/**
+ * 判断两个函数组件的代码差异
+ *
+ * 分析策略：
+ * 1. 解析函数代码，提取所有 createView/branch/dynamic 等 UI API 调用
+ * 2. 将这些调用识别为 UI 描述代码
+ * 3. 其余代码识别为非 UI 代码（逻辑代码）
+ * 4. 分别比较 UI 代码和非 UI 代码是否变化
+ *
+ * @param newCode 新函数代码
+ * @param oldCode 旧函数代码
+ * @returns {ChangeCode} 变更检测结果
+ */
+export declare function diffComponentChange(newCode: string, oldCode: string): ChangeCode;

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { type Plugin } from 'vite';
+export type * from './components.js';
+/**
+ * vite-plugin-vitarx 配置选项
+ *
+ * 暂无配置选项
+ */
+export interface VitePluginVitarxOptions {
+}
+/**
+ * vite-plugin-vitarx
+ *
+ * 功能：
+ * - jsx -> createView 编译转换
+ * - 支持 v-if、v-else-if、v-else 、v-model 等编译宏指令
+ * - 支持 Switch , IfBlock 等编译宏组件
+ * - 开发时 HMR 热更新相关代码注入与功能支持
+ *
+ * @param _options - 暂无可选配置。
+ * @returns - vite插件对象。
+ */
+export default function vitarx(_options?: VitePluginVitarxOptions): Plugin;

package/dist/passes/components/ifBlock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * IfBlock 组件处理器
+ * 将 <IfBlock><div v-if>...</div><div v-else>...</div></IfBlock> 编译为 branch 调用
+ * @module passes/components/ifBlock
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * 处理 IfBlock 组件
+ */
+export declare function processIfBlock(path: NodePath<t.JSXElement>, ctx: TransformContext): void;

package/dist/passes/components/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 编译宏组件处理模块
+ * 包含 Switch、IfBlock 等纯编译组件的转换
+ * @module passes/components
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * 处理纯编译组件
+ * 根据组件名称分发到对应的处理器
+ * @param path - JSX 元素路径
+ * @param ctx - 转换上下文
+ */
+export declare function processPureCompileComponent(path: NodePath<t.JSXElement>, ctx: TransformContext): void;
+export { processSwitch } from './switch.js';
+export { processIfBlock } from './ifBlock.js';

package/dist/passes/components/switch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Switch 组件处理器
+ * 将 <Switch><Match when={cond}>...</Match></Switch> 编译为 branch 调用
+ * @module passes/components/switch
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * 处理 Switch 组件
+ * @param path - JSX 元素路径
+ * @param ctx - 转换上下文
+ */
+export declare function processSwitch(path: NodePath<t.JSXElement>, ctx: TransformContext): void;

package/dist/passes/directives/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 指令处理模块
+ * @module passes/directives
+ */
+export { processVIfChain } from './vIf.js';
+export { processDirectives } from './processDirectives.js';

package/dist/passes/directives/processDirectives.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 指令处理模块
+ * 处理 v-show 等指令
+ * @module passes/directives/processDirectives
+ */
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * 处理指令
+ * 将指令转换为 withDirectives 调用
+ * @param viewCall - 视图调用表达式
+ * @param directives - 指令映射
+ * @param ctx - 转换上下文
+ * @returns 处理后的调用表达式
+ */
+export declare function processDirectives(viewCall: t.CallExpression, directives: Map<string, t.Expression>, ctx: TransformContext): t.CallExpression;

package/dist/passes/directives/vIf.d.ts

@@ -0,0 +1,20 @@
+/**
+ * v-if 链处理器
+ * 处理 Fragment 中的 v-if/v-else-if/v-else 链
+ * @module passes/directives/vIf
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * JSX 元素转换函数类型
+ */
+type TransformJSXElementFn = (node: t.JSXElement, ctx: TransformContext, handleVIf: boolean) => t.Expression | null;
+/**
+ * 处理 Fragment 中的 v-if 链
+ * @param path - JSX Fragment 路径
+ * @param ctx - 转换上下文
+ * @param transformJSXElement - JSX 元素转换函数
+ */
+export declare function processVIfChain(path: NodePath<t.JSXFragment>, ctx: TransformContext, transformJSXElement: TransformJSXElementFn): void;
+export {};

package/dist/passes/hmr/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * HMR 注入模块入口
+ * @module passes/hmr
+ */
+export { injectHMRSupport } from './inject.js';

package/dist/passes/hmr/inject.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HMR 代码注入模块
+ * 在 HMR 模式下为组件函数注入热更新支持代码
+ * @module passes/hmr
+ */
+import * as t from '@babel/types';
+import { type ComponentInfo } from '../../utils/index.js';
+/**
+ * 注入 HMR 支持
+ * 主入口函数，为所有组件注入完整的 HMR 支持
+ * @param program - AST Program 节点
+ * @param components - 组件信息列表
+ * @param filename - 文件名
+ */
+export declare function injectHMRSupport(program: t.Program, components: ComponentInfo[], filename: string): void;

package/dist/passes/imports/collectImports.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 导入收集模块
+ * 负责收集现有导入信息和本地变量绑定
+ * @module passes/imports/collectImports
+ */
+import * as t from '@babel/types';
+/**
+ * 收集现有导入信息
+ * @param program - AST Program 节点
+ * @returns 本地变量名集合和 vitarx 导入映射
+ */
+export declare function collectExistingImports(program: t.Program): {
+    localNames: Set<string>;
+    vitarxImports: Map<string, string>;
+};
+/**
+ * 收集本地变量绑定
+ * 包括导入绑定、变量声明、函数声明、类声明
+ * @param program - AST Program 节点
+ * @returns 本地变量名集合
+ */
+export declare function collectLocalBindings(program: t.Program): Set<string>;

package/dist/passes/imports/collectRefVariables.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Ref 变量收集模块
+ * 负责识别 ref API 别名和收集 ref 变量
+ * @module passes/imports/collectRefVariables
+ */
+import * as t from '@babel/types';
+import type { RefApiAliases } from '../../context.js';
+/**
+ * 收集 ref API 的别名
+ * 识别从 vitarx 或 @vitarx/responsive 导入的 ref/toRef/toRefs/shallowRef/computed
+ * @param program - AST Program 节点
+ * @returns ref API 别名映射
+ */
+export declare function collectRefApiAliases(program: t.Program): RefApiAliases;
+/**
+ * 收集通过 ref API 定义的变量
+ * 包括直接赋值和 toRefs 解构
+ * @param program - AST Program 节点
+ * @param refApiAliases - ref API 别名映射
+ * @returns ref 变量名集合
+ */
+export declare function collectRefVariables(program: t.Program, refApiAliases: RefApiAliases): Set<string>;

package/dist/passes/imports/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 导入处理模块
+ * @module passes/imports
+ */
+export { collectExistingImports, collectLocalBindings } from './collectImports.js';
+export { collectRefApiAliases, collectRefVariables } from './collectRefVariables.js';
+export { injectImports } from './injectImports.js';

package/dist/passes/imports/injectImports.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 导入注入模块
+ * 负责动态注入 vitarx 导入语句
+ * @module passes/imports/injectImports
+ */
+import * as t from '@babel/types';
+import type { TransformContext } from '../../context.js';
+/**
+ * 注入 vitarx 导入
+ * 根据已使用的 API 动态生成导入语句
+ * @param program - AST Program 节点
+ * @param ctx - 转换上下文
+ */
+export declare function injectImports(program: t.Program, ctx: TransformContext): void;

package/dist/passes/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 编译转换处理模块
+ * @module passes
+ */
+export { collectExistingImports, collectLocalBindings, collectRefApiAliases, collectRefVariables, injectImports } from './imports/index.js';
+export { processPureCompileComponent, processSwitch, processIfBlock } from './components/index.js';
+export { processVIfChain, processDirectives } from './directives/index.js';
+export { processChildren, processJSXElement, transformJSXElement, processJSXFragment } from './jsx/index.js';
+export { processProps, type PropsResult } from './props/index.js';
+export { injectHMRSupport } from './hmr/index.js';

package/dist/passes/jsx/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * JSX 处理模块
+ * @module passes/jsx
+ */
+export { processChildren } from './processChildren.js';
+export { processJSXElement, transformJSXElement } from './processJSXElement.js';
+export { processJSXFragment } from './processJSXFragment.js';

package/dist/passes/jsx/processChildren.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 子元素处理模块
+ * 处理 JSX 元素的子节点
+ * @module passes/jsx/processChildren
+ */
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * 处理子节点数组
+ * @param children - 子节点数组
+ * @param ctx - 转换上下文
+ * @returns 处理后的表达式数组
+ */
+export declare function processChildren(children: t.Node[], ctx: TransformContext): t.Expression[];

package/dist/passes/jsx/processJSXElement.d.ts

@@ -0,0 +1,22 @@
+/**
+ * JSX 元素处理模块
+ * 将 JSX 元素转换为 createView 调用
+ * @module passes/jsx/processJSXElement
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * 处理 JSX 元素
+ * @param path - JSX 元素路径
+ * @param ctx - 转换上下文
+ */
+export declare function processJSXElement(path: NodePath<t.JSXElement>, ctx: TransformContext): void;
+/**
+ * 转换 JSX 元素为表达式
+ * @param node - JSX 元素节点
+ * @param ctx - 转换上下文
+ * @param handleVIf - 是否处理 v-if 指令
+ * @returns 转换后的表达式
+ */
+export declare function transformJSXElement(node: t.JSXElement, ctx: TransformContext, handleVIf?: boolean): t.Expression | null;

package/dist/passes/jsx/processJSXFragment.d.ts

@@ -0,0 +1,14 @@
+/**
+ * JSX Fragment 处理模块
+ * 将 JSX Fragment 转换为 createView(Fragment, ...) 调用
+ * @module passes/jsx/processJSXFragment
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+/**
+ * 处理 JSX Fragment
+ * @param path - JSX Fragment 路径
+ * @param ctx - 转换上下文
+ */
+export declare function processJSXFragment(path: NodePath<t.JSXFragment>, ctx: TransformContext): void;

package/dist/passes/props/attribute.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 属性处理模块
+ * 负责处理 JSX 元素的各类属性，包括普通属性、展开属性、命名空间属性等
+ * @module passes/props/attribute
+ */
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+import type { AttributeResult } from './types.js';
+/**
+ * 处理展开属性 {...props}
+ * 将展开属性转换为 v-bind 特殊属性格式
+ * @param attr - JSX 展开属性节点
+ * @param hasVBind - 是否已存在 v-bind
+ * @param node - JSX 元素节点（用于错误定位）
+ * @returns 转换后的属性对象，或 null（如果已存在 v-bind）
+ * @throws {Error} E001 - 当已存在 v-bind 时抛出
+ */
+export declare function processSpreadAttribute(attr: t.JSXSpreadAttribute, hasVBind: boolean, node: t.JSXElement): {
+    property: t.ObjectProperty;
+    hasVBind: boolean;
+} | null;
+/**
+ * 处理单个 JSX 属性
+ * 根据属性名类型分发到不同的处理逻辑
+ * @param attr - JSX 属性节点
+ * @param existingPropNames - 已存在的属性名集合
+ * @param ctx - 转换上下文
+ * @returns 属性处理结果
+ */
+export declare function processAttribute(attr: t.JSXAttribute, existingPropNames: Set<string>, ctx: TransformContext): AttributeResult;

package/dist/passes/props/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Props 处理模块入口
+ * 负责处理 JSX 元素的属性，包括 v-model 特殊指令
+ * @module passes/props
+ */
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+import type { PropsResult } from './types.js';
+export type { PropsResult, VModelState, AttributeResult } from './types.js';
+/**
+ * 处理 JSX 元素的属性
+ * 将 JSX 属性转换为运行时 props 对象，并提取指令
+ *
+ * 处理流程：
+ * 1. 遍历所有属性，分类处理
+ * 2. 展开属性转换为 v-bind 格式
+ * 3. 普通属性转换为对象属性或 getter
+ * 4. 指令属性提取到 directives Map
+ * 5. v-model 特殊处理，生成 modelValue 和 onUpdate:modelValue
+ *
+ * @param node - JSX 元素节点
+ * @param ctx - 转换上下文
+ * @param hasChildren - 是否有子元素（有子元素时跳过 children 属性）
+ * @returns 处理结果，包含 props 对象、指令映射和 v-bind 标记
+ *
+ * @example
+ * ```tsx
+ * // 输入
+ * <Input v-model={value} placeholder="text" disabled />
+ *
+ * // 输出 props
+ * {
+ *   modelValue: get() { return value.value },
+ *   'onUpdate:modelValue': v => value.value = v,
+ *   placeholder: "text",
+ *   disabled: true
+ * }
+ * ```
+ */
+export declare function processProps(node: t.JSXElement, ctx: TransformContext, hasChildren?: boolean): PropsResult;

package/dist/passes/props/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Props 处理模块 - 类型定义
+ * @module passes/props/types
+ */
+import * as t from '@babel/types';
+/**
+ * Props 处理结果
+ */
+export interface PropsResult {
+    /** 处理后的 props 对象表达式，无属性时为 null */
+    props: t.ObjectExpression | null;
+    /** 指令映射表，key 为指令名，value 为指令值表达式 */
+    directives: Map<string, t.Expression>;
+    /** 是否包含 v-bind 展开属性 */
+    hasVBind: boolean;
+}
+/**
+ * v-model 指令状态
+ */
+export interface VModelState {
+    /** 是否存在 v-model 指令 */
+    hasVModel: boolean;
+    /** v-model 绑定的值表达式 */
+    value: t.Expression | null;
+    /** v-model 属性节点，用于错误定位 */
+    node: t.JSXAttribute | null;
+}
+/**
+ * 属性处理结果联合类型
+ * - directive: 指令类型属性
+ * - property: 普通属性
+ */
+export type AttributeResult = {
+    type: 'directive';
+    name: string;
+    value: t.Expression;
+    isVBind: boolean;
+    isVModel: boolean;
+} | {
+    type: 'property';
+    property: t.ObjectProperty | t.ObjectMethod;
+};

package/dist/passes/props/vmodel.d.ts

@@ -0,0 +1,27 @@
+/**
+ * v-model 指令处理模块
+ * 负责处理 JSX 元素的 v-model 双向绑定指令
+ * @module passes/props/vmodel
+ */
+import * as t from '@babel/types';
+import { TransformContext } from '../../context.js';
+import type { VModelState } from './types.js';
+/**
+ * 从属性列表中提取 v-model 状态
+ * @param attributes - JSX 元素属性列表
+ * @returns v-model 状态对象
+ */
+export declare function extractVModelState(attributes: (t.JSXAttribute | t.JSXSpreadAttribute)[]): VModelState;
+/**
+ * 创建 v-model 相关的 props
+ * 生成 modelValue getter 和 onUpdate:modelValue 回调
+ * @param value - v-model 绑定的值表达式
+ * @param attrNode - v-model 属性节点（用于错误定位）
+ * @param existingPropNames - 已存在的属性名集合（用于冲突检测）
+ * @param node - JSX 元素节点
+ * @param ctx - 转换上下文
+ * @returns 包含 modelValue 和 onUpdate:modelValue 的属性数组
+ * @throws {Error} E009 - 当 modelValue 或 onUpdate:modelValue 已存在时
+ * @throws {Error} E010 - 当 v-model 绑定值不是 Identifier 或 MemberExpression 时
+ */
+export declare function createVModelProps(value: t.Expression, attrNode: t.JSXAttribute | null, existingPropNames: Set<string>, node: t.JSXElement, ctx: TransformContext): (t.ObjectMethod | t.ObjectProperty)[];

package/dist/transform.d.ts

@@ -0,0 +1,15 @@
+export interface TransformResult {
+    code: string;
+    map: any;
+}
+export interface CompileOptions {
+    hmr: boolean;
+    dev: boolean;
+    ssr: boolean;
+    runtimeModule: string;
+    sourceMap: boolean | 'inline' | 'both';
+}
+/**
+ * 转换 JSX/TSX 代码
+ */
+export declare function transform(code: string, id: string, options: CompileOptions): Promise<TransformResult | null>;

package/dist/utils/ast-builders.d.ts

@@ -0,0 +1,75 @@
+import { type ArrowFunctionExpression, type CallExpression, type Expression, type ObjectExpression, type SourceLocation } from '@babel/types';
+import type { VitarxImportAliases } from '../context.js';
+/**
+ * 创建 unref 调用
+ * @param argument - 参数表达式
+ * @param alias - unref 别名
+ * @returns CallExpression
+ */
+export declare function createUnrefCall(argument: Expression, alias?: string): CallExpression;
+/**
+ * 创建 access 调用
+ * @param object - 对象表达式
+ * @param key - 键表达式
+ * @param alias - access 别名
+ * @returns CallExpression
+ */
+export declare function createAccessCall(object: Expression, key: Expression, alias?: string): CallExpression;
+/**
+ * 创建 dynamic 调用
+ * @param argument - 参数表达式
+ * @param alias - dynamic 别名
+ * @returns CallExpression
+ */
+export declare function createDynamicCall(argument: Expression, alias?: string): CallExpression;
+/**
+ * 创建 branch 调用
+ * @param condition - 条件函数
+ * @param branches - 分支函数数组
+ * @param alias - branch 别名
+ * @returns CallExpression
+ */
+export declare function createBranchCall(condition: ArrowFunctionExpression, branches: ArrowFunctionExpression[], alias?: string): CallExpression;
+/**
+ * 创建 createView 调用
+ * @param type - 元素类型
+ * @param props - props 对象
+ * @param locInfo - 位置信息对象
+ * @param alias - createView 别名
+ * @returns CallExpression
+ */
+export declare function createCreateViewCall(type: Expression, props: ObjectExpression | null, locInfo?: ObjectExpression | null, alias?: string): CallExpression;
+/**
+ * 创建 withDirectives 调用
+ * @param view - 视图节点
+ * @param directives - 指令数组，每项为 [指令名, 指令值]
+ * @param alias - withDirectives 别名
+ * @returns CallExpression
+ */
+export declare function createWithDirectivesCall(view: Expression, directives: Array<[string, Expression]>, alias?: string): CallExpression;
+/**
+ * 创建箭头函数
+ * @param body - 函数体表达式
+ * @returns ArrowFunctionExpression
+ */
+export declare function createArrowFunction(body: Expression): ArrowFunctionExpression;
+/**
+ * 创建位置信息对象
+ * @param filename - 文件名
+ * @param loc - 源码位置
+ * @returns ObjectExpression
+ */
+export declare function createLocationObject(filename: string, loc: SourceLocation): ObjectExpression;
+/**
+ * 为调用表达式添加 @__PURE__ 注释
+ * @param node - 调用表达式节点
+ * @returns 添加注释后的节点
+ */
+export declare function addPureComment<T extends CallExpression>(node: T): T;
+/**
+ * 获取 API 别名
+ * @param aliases - 别名映射
+ * @param name - API 名称
+ * @returns 别名或原名
+ */
+export declare function getAlias(aliases: VitarxImportAliases, name: keyof VitarxImportAliases): string;

package/dist/utils/ast-guards.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AST 类型守卫函数
+ * 用于判断节点类型
+ * @module utils/ast-guards
+ */
+import { type Node } from '@babel/types';
+/**
+ * 判断 JSXText 是否为纯空白文本
+ * @param node - AST 节点
+ * @returns 是否为纯空白文本
+ */
+export declare function isWhitespaceJSXText(node: Node): boolean;

package/dist/utils/branch-factory.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Branch 调用工厂模块
+ * 统一处理条件分支的生成
+ * @module utils/branch-factory
+ */
+import * as t from '@babel/types';
+import type { TransformContext } from '../context.js';
+/**
+ * 条件分支配置
+ */
+export interface BranchConfig {
+    /** 条件表达式数组 */
+    conditions: t.Expression[];
+    /** 分支函数数组 */
+    branches: t.ArrowFunctionExpression[];
+    /** 是否使用 unref 包装标识符条件 */
+    useRef?: boolean;
+}
+/**
+ * 创建 branch 调用
+ * @param config - 分支配置
+ * @param ctx - 转换上下文
+ * @returns branch 调用表达式
+ */
+export declare function createBranch(config: BranchConfig, ctx: TransformContext): t.CallExpression;
+/**
+ * 构建嵌套条件表达式
+ * 从后向前构建三元表达式链
+ */
+export declare function buildNestedCondition(conditions: t.Expression[], ctx: TransformContext, useRef?: boolean): t.Expression;
+/**
+ * 从条件数组和分支节点创建完整的 branch 调用
+ * @param conditions - 条件表达式数组
+ * @param branchNodes - 分支节点数组（会被包装为箭头函数）
+ * @param ctx - 转换上下文
+ * @returns branch 调用表达式
+ */
+export declare function createBranchFromNodes(conditions: t.Expression[], branchNodes: t.Expression[], ctx: TransformContext): t.CallExpression;
+/**
+ * 创建简单的二元条件 branch（用于三元表达式）
+ * @param condition - 条件表达式
+ * @param consequent - 真值分支
+ * @param alternate - 假值分支
+ * @param ctx - 转换上下文
+ * @returns branch 调用表达式
+ */
+export declare function createBinaryBranch(condition: t.Expression, consequent: t.Expression, alternate: t.Expression, ctx: TransformContext): t.CallExpression;

package/dist/utils/component-collect.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AST 收集模块
+ * 负责收集导入、导出、组件等信息的收集
+ * @module passes/transform/collect
+ */
+import * as t from '@babel/types';
+/**
+ * 组件信息
+ */
+export interface ComponentInfo {
+    name: string;
+    node: t.FunctionDeclaration | t.ArrowFunctionExpression | t.FunctionExpression;
+}
+/**
+ * 收集模块中的组件函数
+ */
+export declare function collectComponentFunctions(program: t.Program): ComponentInfo[];

package/dist/utils/generate.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 生成唯一的别名
+ * 从 $1 开始递增，直到找到不冲突的名称
+ */
+export declare function generateUniqueAlias(baseName: string, existingNames: Set<string>): string;

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+export { isWhitespaceJSXText } from './ast-guards.js';
+export { getJSXElementName, isPureCompileComponent, isComponent, isNativeElement, getJSXAttributeByName, hasDirective, getDirectiveValue, isVIfChain, isVIf, isVElseIf, isVElse, removeVDirectives, removeAttribute, filterWhitespaceChildren, validateMatchInSwitch } from './jsx-helpers.js';
+export { createUnrefCall, createAccessCall, createDynamicCall, createBranchCall, createCreateViewCall, createWithDirectivesCall, createArrowFunction, createLocationObject, addPureComment, getAlias } from './ast-builders.js';
+export { collectPatternBindings, collectObjectPatternBindings } from './pattern-helpers.js';
+export { createBranch, createBinaryBranch, buildNestedCondition, type BranchConfig } from './branch-factory.js';
+export { validateVIfChain, collectVIfChainInfo, collectFragmentVIfChains, type VIfChainInfo } from './vif-helpers.js';
+export { collectComponentFunctions, type ComponentInfo } from './component-collect.js';
+export { generateUniqueAlias } from './generate.js';

package/dist/utils/jsx-helpers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * JSX 相关工具函数
+ * @module utils/jsx-helpers
+ */
+import * as t from '@babel/types';
+import { type Expression, type JSXAttribute, type JSXElement } from '@babel/types';
+/**
+ * 获取 JSX 元素的名称
+ */
+export declare function getJSXElementName(node: JSXElement): string | null;
+/**
+ * 判断名称是否为纯编译组件
+ */
+export declare function isPureCompileComponent(name: string): boolean;
+/**
+ * 判断名称是否为组件（首字母大写）
+ */
+export declare function isComponent(name: string): boolean;
+/**
+ * 判断名称是否为原生元素
+ */
+export declare function isNativeElement(name: string): boolean;
+/**
+ * 根据名称获取 JSX 属性
+ */
+export declare function getJSXAttributeByName(node: JSXElement, name: string): JSXAttribute | undefined;
+/**
+ * 检查元素是否具有指定指令
+ */
+export declare function hasDirective(node: JSXElement, directiveName: string): boolean;
+/**
+ * 获取指令的值
+ */
+export declare function getDirectiveValue(node: JSXElement, directiveName: string): Expression | null;
+/**
+ * 检查元素是否为 v-if 链的一部分
+ */
+export declare function isVIfChain(node: JSXElement): boolean;
+/**
+ * 检查元素是否有 v-if 指令
+ */
+export declare function isVIf(node: JSXElement): boolean;
+/**
+ * 检查元素是否有 v-else-if 指令
+ */
+export declare function isVElseIf(node: JSXElement): boolean;
+/**
+ * 检查元素是否有 v-else 指令
+ */
+export declare function isVElse(node: JSXElement): boolean;
+/**
+ * 移除元素上所有 v- 开头的指令属性
+ */
+export declare function removeVDirectives(node: JSXElement): void;
+/**
+ * 移除元素上指定名称的属性
+ */
+export declare function removeAttribute(node: JSXElement, attrName: string): void;
+/**
+ * 过滤掉空白文本子节点
+ */
+export declare function filterWhitespaceChildren(children: t.Node[]): t.Node[];
+/**
+ * 校验 Match 组件必须在 Switch 内使用
+ * @param children - 子节点数组
+ */
+export declare function validateMatchInSwitch(children: t.Node[]): void;

package/dist/utils/pattern-helpers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AST 模式处理辅助函数
+ * 用于处理解构模式、绑定模式等
+ * @module utils/pattern-helpers
+ */
+import type { LVal, ObjectPattern } from '@babel/types';
+/**
+ * 从绑定模式中收集变量名
+ * 支持标识符、对象模式、数组模式
+ * @param pattern - 绑定模式
+ * @param variables - 变量名集合
+ */
+export declare function collectPatternBindings(pattern: LVal, variables: Set<string>): void;
+/**
+ * 从对象解构模式中收集变量名
+ * 专门用于 toRefs 解构场景
+ * @param pattern - 对象模式
+ * @param variables - 变量名集合
+ */
+export declare function collectObjectPatternBindings(pattern: ObjectPattern, variables: Set<string>): void;

package/dist/utils/vif-helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * v-if 链处理工具模块
+ * 统一处理 v-if/v-else-if/v-else 链的验证和收集
+ * @module utils/vif-helpers
+ */
+import * as t from '@babel/types';
+/**
+ * v-if 链信息
+ */
+export interface VIfChainInfo {
+    /** 链中的元素节点 */
+    nodes: t.JSXElement[];
+    /** 条件表达式数组 */
+    conditions: t.Expression[];
+    /** 结束索引 */
+    endIndex: number;
+}
+/**
+ * 验证 v-if 链的合法性
+ */
+export declare function validateVIfChain(children: t.JSXElement[]): void;
+/**
+ * 从 JSX 元素数组收集 v-if 链信息
+ */
+export declare function collectVIfChainInfo(nodes: t.JSXElement[]): VIfChainInfo;
+/**
+ * 收集 Fragment 中的 v-if 链
+ */
+export declare function collectFragmentVIfChains(children: t.Node[]): Array<VIfChainInfo & {
+    endIndex: number;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitarx/plugin-vite",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "description": "The official plugin for Vitarx support in Vite.",
   "author": "ZhuChongLin <8210856@qq.com>",
   "license": "MIT",