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

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/index.js

@@ -43,13 +43,12 @@ export default function vitarx(_options) {
         },
         configResolved(config) {
             viteConfig = config;
-            const sourcemap = config.build.sourcemap;
             compileOptions = {
                 dev: isDEV,
                 ssr: isSSR,
                 hmr: isDEV && !isSSR,
                 runtimeModule: 'vitarx',
-                sourceMap: sourcemap === 'inline' ? 'inline' : sourcemap === true ? 'both' : false
+                sourceMap: false
             };
         },
         async transform(code, id) {
@@ -57,9 +56,9 @@ export default function vitarx(_options) {
             if (result) {
                 return await transformWithOxc(result.code, id, {
                     jsx: 'preserve'
-                }, result.map, viteConfig);
+                }, this.getCombinedSourcemap(), viteConfig);
             }
-            return result;
+            return null;
         }
     };
 }

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

package/dist/passes/directives/processDirectives.js

@@ -20,9 +20,9 @@ export function processDirectives(viewCall, directives, ctx) {
         return viewCall;
     }
     const directiveArray = [];
-    for (const [name, value] of directives) {
+    for (const [name, info] of directives) {
         const directiveName = name.slice(2); // 移除 'v-' 前缀
-        const directiveValue = buildDirectiveValue(value, ctx);
+        const directiveValue = buildDirectiveValue(info.value, info.arg, ctx);
         directiveArray.push([directiveName, directiveValue]);
     }
     markImport(ctx, 'withDirectives');
@@ -32,15 +32,20 @@ export function processDirectives(viewCall, directives, ctx) {
 /**
  * 构建指令值对象
  */
-function buildDirectiveValue(value, ctx) {
+function buildDirectiveValue(value, arg, ctx) {
+    const properties = [];
+    // 添加 value 属性
     if (isIdentifier(value)) {
         markImport(ctx, 'unref');
         const unrefAlias = getAlias(ctx.vitarxAliases, 'unref');
-        return t.objectExpression([
-            t.objectMethod('get', t.identifier('value'), [], t.blockStatement([t.returnStatement(t.callExpression(t.identifier(unrefAlias), [value]))]))
-        ]);
+        properties.push(t.objectMethod('get', t.identifier('value'), [], t.blockStatement([t.returnStatement(t.callExpression(t.identifier(unrefAlias), [value]))])));
     }
-    return t.objectExpression([
-        t.objectMethod('get', t.identifier('value'), [], t.blockStatement([t.returnStatement(value)]))
-    ]);
+    else {
+        properties.push(t.objectMethod('get', t.identifier('value'), [], t.blockStatement([t.returnStatement(value)])));
+    }
+    // 添加 arg 属性
+    if (arg) {
+        properties.push(t.objectProperty(t.identifier('arg'), t.stringLiteral(arg)));
+    }
+    return t.objectExpression(properties);
 }

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;