@vitarx/plugin-vite 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,27 @@
+# MIT License
+
+## 版权声明
+
+版权所有 (c) 2024-present 朱冲林
+
+## 许可条款
+
+特此授予任何获得本软件及相关文档文件（以下简称“软件”）副本的个人或组织以下权利，且不受限制地行使以下权利：
+
+1. **使用**：允许在任何用途中使用本软件。
+2. **复制**：允许复制本软件。
+3. **修改**：允许修改本软件。
+4. **合并**：允许将本软件合并到其他作品中。
+5. **发布**：允许发布本软件。
+6. **分发**：允许分发本软件。
+7. **再许可**：允许对本软件进行再许可。
+8. **销售**：允许销售本软件的副本。
+
+## 条件
+
+上述版权声明和本许可声明须包含在本软件的所有副本或实质性部分中。
+
+## 免责声明
+
+本软件按“原样”提供，不提供任何形式的明示或暗示担保，包括但不限于对适销性、特定用途适用性和非侵权性的担保。
+在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同、侵权或其他行为中产生的，还是与本软件或使用本软件有关的。

package/README.md

@@ -0,0 +1,298 @@
+# @vitarx/plugin-vite
+
+Vitarx 的 Vite 编译插件，提供 JSX 到 `createView` 的编译转换、指令支持和 HMR 热更新功能。
+
+## 特性
+
+- 🚀 **JSX 编译** - 将 JSX 语法编译为高效的 `createView` 调用
+- 📦 **编译宏指令** - 支持 `v-if`、`v-else-if`、`v-else`、`v-model`、`v-show` 等指令
+- 🧩 **编译宏组件** - 内置 `Switch`、`Match`、`IfBlock` 纯编译组件
+- 🔥 **HMR 支持** - 开发模式下自动注入热更新代码，支持组件状态保留
+- 📝 **TypeScript** - 完整的 TypeScript 类型支持
+
+## 安装
+
+```bash
+npm install @vitarx/plugin-vite
+# 或
+pnpm add @vitarx/plugin-vite
+# 或
+yarn add @vitarx/plugin-vite
+```
+
+## 使用方法
+
+### 配置 Vite
+
+在 `vite.config.ts` 中配置插件：
+
+```typescript
+import { defineConfig } from 'vite'
+import vitarx from '@vitarx/plugin-vite'
+
+export default defineConfig({
+  plugins: [vitarx()]
+})
+```
+
+### JSX 编译
+
+插件会自动将 JSX 语法编译为 `createView` 调用：
+
+```jsx
+// 编译前
+const App = () => <div className="container">Hello World</div>
+
+// 编译后
+import { createView } from 'vitarx'
+const App = () => /* @__PURE__ */createView('div', {
+  className: 'container',
+  children: 'Hello World'
+})
+```
+
+## 编译宏指令
+
+### v-if / v-else-if / v-else
+
+条件渲染指令，编译为高效的 `branch` 调用：
+
+```jsx
+<>
+  <div v-if={show}>显示内容</div>
+  <span v-else-if={other}>其他内容</span>
+  <p v-else>默认内容</p>
+</>
+```
+
+编译后：
+
+```javascript
+branch(
+  () => unref(show) ? 0 : unref(other) ? 1 : 2,
+  [
+    () => createView('div', { children: '显示内容' }),
+    () => createView('span', { children: '其他内容' }),
+    () => createView('p', { children: '默认内容' })
+  ]
+)
+```
+
+### v-model
+
+双向绑定指令，自动生成 `modelValue` 和 `onUpdate:modelValue`：
+
+```jsx
+<Input v-model={value} />
+```
+
+编译后：
+
+```javascript
+createView(Input, {
+  get modelValue() { return unref(value) },
+  'onUpdate:modelValue': v => { value.value = v }
+})
+```
+
+### v-show
+
+显示/隐藏指令：
+
+```jsx
+<div v-show={visible}>内容</div>
+```
+
+编译后：
+
+```javascript
+withDirectives(
+  createView('div', { children: '内容' }),
+  [['show', { get value() { return unref(visible) } }]]
+)
+```
+
+## 编译宏组件
+
+### Switch / Match
+
+条件分支组件，类似于 JavaScript 的 switch 语句：
+
+```jsx
+<Switch fallback={<div>默认</div>}>
+  <Match when={status === 'loading'}>加载中...</Match>
+  <Match when={status === 'error'}>出错了</Match>
+  <Match when={status === 'success'}>加载成功</Match>
+</Switch>
+```
+
+编译后：
+
+```javascript
+branch(
+  () => status === 'loading' ? 0 : status === 'error' ? 1 : status === 'success' ? 2 : 3,
+  [
+    () => '加载中...',
+    () => '出错了',
+    () => '加载成功',
+    () => createView('div', { children: '默认' })
+  ]
+)
+```
+
+### IfBlock
+
+用于包裹 v-if 链，确保类型正确：
+
+```jsx
+<IfBlock>
+  <div v-if={a}>A</div>
+  <span v-else-if={b}>B</span>
+  <p v-else>C</p>
+</IfBlock>
+```
+
+## Props 处理
+
+### 响应式 Props
+
+插件会自动处理响应式属性：
+
+```jsx
+// ref 变量自动使用 .value
+const count = ref(0);
+<div count={count} />
+// 编译为: get count() { return count.value }
+
+// 普通变量自动使用 unref
+<div className={className} />
+// 编译为: get className() { return unref(className) }
+
+// 成员表达式直接访问
+<div value={props.value} />
+// 编译为: get value() { return props.value }
+```
+
+### v-bind 批量绑定
+
+```jsx
+<div {...props} />
+// 或
+<div v-bind={props} />
+```
+
+## HMR 热更新
+
+开发模式下，插件会自动为导出的组件注入 HMR 支持：
+
+```jsx
+// 编译前
+export const App = () => {
+  const count = ref(0)
+  return <div>{count}</div>
+}
+
+// 编译后（HMR 模式）
+import __$VITARX_HMR$__ from '@vitarx/plugin-vite/hmr-client'
+import { createView as jsxDEV, getInstance } from 'vitarx'
+
+export const App = () => {
+  const __$VITARX_HMR_VIEW_NODE$__ = getInstance()
+  __$VITARX_HMR$__.instance.register(__$VITARX_HMR_VIEW_NODE$__)
+  __$VITARX_HMR_VIEW_NODE$__ && Promise.resolve().then(() => {
+    __$VITARX_HMR_VIEW_NODE$__._$_VITARX_HMR_VIEW_STATE_$_ = {
+      get count() { return count }
+    }
+  })
+  const count = ref(0)
+  return jsxDEV('div', { children: count }, { fileName: '...', lineNumber: 5, columnNumber: 10 })
+}
+
+__$VITARX_HMR$__.instance.bindId(App, 'abc123')
+import.meta.hot.accept(mod => {
+  __$VITARX_HMR$__.instance.update(mod)
+})
+```
+
+### HMR 组件识别规则
+
+只有满足以下条件的函数才会被注入 HMR 支持：
+
+1. **函数名大写字母开头** - 符合组件命名规范
+2. **被导出** - 使用 `export` 导出
+3. **包含 JSX** - 函数体内包含 JSX 语法或返回编译宏组件
+
+## 子元素处理
+
+### 响应式子元素
+
+```jsx
+// 标识符保持原样
+<div>{value}</div>
+
+// 成员表达式使用 access
+<div>{props.value}</div>
+// 编译为: access(props, 'value')
+
+// 条件表达式使用 branch
+<div>{show ? 'yes' : 'no'}</div>
+// 编译为: branch(() => unref(show) ? 0 : 1, [...])
+
+// 逻辑表达式使用 dynamic
+<div>{a && b}</div>
+// 编译为: dynamic(() => a && b)
+```
+
+## API 参考
+
+### 插件选项
+
+```typescript
+interface VitePluginVitarxOptions {
+  // 暂无配置选项
+}
+```
+
+## 目录结构
+
+```
+src/
+├── constants/      # 常量定义
+├── hmr-client/     # HMR 客户端运行时
+├── passes/         # 编译转换处理
+│   ├── components/ # 编译宏组件
+│   ├── directives/ # 指令处理
+│   ├── hmr/        # HMR 注入
+│   ├── imports/    # 导入处理
+│   ├── jsx/        # JSX 转换
+│   └── props/  # 属性处理
+├── utils/          # 公共工具函数
+├── context.ts      # 转换上下文
+├── error.ts        # 错误处理
+├── transform.ts    # 主转换入口
+└── index.ts        # 插件入口
+```
+
+## 错误码
+
+| 错误码  | 描述                          |
+|------|-----------------------------|
+| E001 | 无效的 JSX 属性值                 |
+| E002 | 无效的 v-model 值               |
+| E003 | v-else 没有前置的 v-if           |
+| E004 | v-else-if 没有前置的 v-if        |
+| E005 | 无效的 v-if 值                  |
+| E006 | Switch 子元素必须是 Match 组件      |
+| E007 | Match 组件缺少 when 属性          |
+| E008 | IfBlock 子元素必须包含 v-if 指令     |
+| E009 | v-model 与 modelValue 冲突     |
+| E010 | v-model 值必须是标识符或成员表达式       |
+| E011 | v-model Identifier 必须是 ref  |
+| E012 | Match 组件必须位于 Switch 组件内部    |
+| E013 | Match 组件必须包含子元素             |
+| E014 | IfBlock 组件必须包含子元素           |
+| E015 | Switch 组件必须包含至少一个 Match 子元素 |
+
+## License
+
+MIT

package/dist/components.js

@@ -0,0 +1 @@
+export {};

package/dist/constants/index.js

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

package/dist/context.js

@@ -0,0 +1,78 @@
+/**
+ * UI 相关的 API 名称列表
+ * 这些 API 用于创建视图，在 HMR 时需要识别
+ */
+export const UI_API_NAMES = ['createView', 'branch', 'dynamic', 'access', 'withDirectives'];
+/**
+ * 创建转换上下文
+ * @param code - 源代码
+ * @param id - 文件标识符
+ * @param options - 编译选项
+ * @param ast - AST 节点
+ * @returns 转换上下文对象
+ */
+export function createContext(code, id, options, ast) {
+    const filename = id.split('?')[0];
+    return {
+        code,
+        id,
+        filename,
+        options,
+        ast,
+        imports: {
+            createView: false,
+            Fragment: false,
+            branch: false,
+            dynamic: false,
+            access: false,
+            withDirectives: false,
+            unref: false,
+            isRef: false
+        },
+        existingImports: new Set(),
+        vitarxAliases: {
+            createView: null,
+            Fragment: null,
+            branch: null,
+            dynamic: null,
+            access: null,
+            withDirectives: null,
+            unref: null,
+            isRef: null
+        },
+        refApiAliases: {
+            ref: null,
+            toRef: null,
+            toRefs: null,
+            shallowRef: null,
+            computed: null
+        },
+        refVariables: new Set(),
+        uiApiAliases: new Set(),
+        warnings: []
+    };
+}
+/**
+ * 标记需要注入的导入
+ * @param ctx - 转换上下文
+ * @param name - 导入名称
+ */
+export function markImport(ctx, name) {
+    ctx.imports[name] = true;
+}
+/**
+ * 记录 UI API 别名
+ * @param ctx - 转换上下文
+ * @param alias - API 别名
+ */
+export function markUiApiAlias(ctx, alias) {
+    ctx.uiApiAliases.add(alias);
+}
+/**
+ * 添加编译警告
+ * @param ctx - 转换上下文
+ * @param warning - 编译警告
+ */
+export function addWarning(ctx, warning) {
+    ctx.warnings.push(warning);
+}

package/dist/error.js

@@ -0,0 +1,156 @@
+/**
+ * 编译器错误类
+ * 包含错误代码和位置信息
+ */
+export class CompilerError extends Error {
+    constructor(options) {
+        super(`[${options.code}] ${options.message}${options.loc ? ` at line ${options.loc.line}:${options.loc.column}` : ''}`);
+        /** 错误代码 */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** 错误位置 */
+        Object.defineProperty(this, "loc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'CompilerError';
+        this.code = options.code;
+        this.loc = options.loc ?? (options.node?.loc ? {
+            line: options.node.loc.start.line,
+            column: options.node.loc.start.column
+        } : undefined);
+    }
+}
+/**
+ * 错误代码枚举
+ */
+export const ErrorCodes = {
+    /** 不能同时使用展开属性和 v-bind */
+    E001: 'E001',
+    /** 重复的展开属性或属性键 */
+    E002: 'E002',
+    /** v-else 没有前置的 v-if */
+    E003: 'E003',
+    /** v-else-if 没有前置的 v-if */
+    E004: 'E004',
+    /** v-if 链不连续 */
+    E005: 'E005',
+    /** Switch 组件有无效子节点 */
+    E006: 'E006',
+    /** Match 组件缺少 when 属性 */
+    E007: 'E007',
+    /** IfBlock 有无效子元素 */
+    E008: 'E008',
+    /** v-model 与 modelValue 或 onUpdate:modelValue 冲突 */
+    E009: 'E009',
+    /** v-model 值必须是 Identifier 或 MemberExpression */
+    E010: 'E010',
+    /** v-model Identifier 必须是 ref */
+    E011: 'E011',
+    /** Match 组件必须在 Switch 内使用 */
+    E012: 'E012',
+    /** Match 组件必须有子元素 */
+    E013: 'E013',
+    /** IfBlock 组件必须有子元素 */
+    E014: 'E014',
+    /** Switch 组件必须有 Match 子元素 */
+    E015: 'E015',
+};
+/**
+ * 警告代码枚举
+ */
+export const WarningCodes = {
+    /** children 属性和子元素同时存在 */
+    W001: 'W001',
+};
+/**
+ * 错误消息映射
+ */
+export const ErrorMessages = {
+    E001: 'Cannot use both spread attribute and v-bind at the same time',
+    E002: 'Duplicate spread attributes or duplicate property keys',
+    E003: 'v-else found without preceding v-if',
+    E004: 'v-else-if found without preceding v-if',
+    E005: 'v-if chain is not continuous',
+    E006: 'Switch component has invalid child nodes',
+    E007: 'Match component is missing "when" attribute',
+    E008: 'IfBlock has invalid child elements',
+    E009: 'v-model cannot be used with modelValue or onUpdate:modelValue',
+    E010: 'v-model value must be an Identifier or MemberExpression',
+    E011: 'v-model Identifier must be a ref',
+    E012: 'Match component must be used inside Switch',
+    E013: 'Match component must have children',
+    E014: 'IfBlock component must have children',
+    E015: 'Switch component must have at least one Match child',
+};
+/**
+ * 警告消息映射
+ */
+export const WarningMessages = {
+    W001: 'Both "children" attribute and child elements are present. Child elements will take precedence.',
+};
+/**
+ * 创建编译错误
+ * @param code - 错误代码
+ * @param node - 相关 AST 节点
+ * @param additionalMessage - 附加消息
+ * @returns 编译错误实例
+ */
+export function createError(code, node, additionalMessage) {
+    const message = ErrorMessages[code] + (additionalMessage ? `: ${additionalMessage}` : '');
+    return new CompilerError({ code, message, node });
+}
+/**
+ * 编译警告类
+ */
+export class CompilerWarning {
+    constructor(code, message, loc) {
+        /** 警告代码 */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** 警告消息 */
+        Object.defineProperty(this, "message", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** 警告位置 */
+        Object.defineProperty(this, "loc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.code = code;
+        this.message = message;
+        this.loc = loc;
+    }
+    toString() {
+        return `[${this.code}] ${this.message}${this.loc ? ` at line ${this.loc.line}:${this.loc.column}` : ''}`;
+    }
+}
+/**
+ * 创建编译警告
+ * @param code - 警告代码
+ * @param node - 相关 AST 节点
+ * @returns 编译警告实例
+ */
+export function createWarning(code, node) {
+    const message = WarningMessages[code];
+    const loc = node?.loc ? {
+        line: node.loc.start.line,
+        column: node.loc.start.column
+    } : undefined;
+    return new CompilerWarning(code, message, loc);
+}