@love-sqjm/magic 2026.4.15

package/README.md

@@ -0,0 +1,93 @@
+# Magic 框架
+
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SQJM/magic)
+[![version](https://img.shields.io/badge/version-1.0.0-green.svg)](https://github.com/SQJM/magic)
+
+## 概述
+
+**Magic** 是一个基于 Bun.js 运行的全栈 Web 开发框架，旨在提供高效、简洁的全栈开发体验。通过自定义的 `.m` 文件格式，开发者可以将模板、样式和脚本整合到单一文件中，极大简化了组件化开发的复杂度。
+
+## 核心特性
+
+| 特性 | 描述 |
+|------|------|
+| **一体化文件格式** | `.m` 文件整合 HTML 模板、CSS 样式、JavaScript 脚本 |
+| **多平台支持** | Web 浏览器、Node-Webkit 桌面应用、可复用模块 |
+| **编译时优化** | Babel AST 转换、CSS 作用域、代码压缩 |
+| **热更新支持** | WebSocket 实时刷新开发 |
+| **宏系统** | 支持文件包含、数据绑定等编译时处理 |
+| **模块化架构** | 清晰的编译器流水线设计 |
+
+## 技术栈
+
+| 类别 | 技术选型 |
+|------|----------|
+| 运行时 | Bun.js |
+| CLI | Commander.js |
+| HTML 解析 | node-html-parser |
+| CSS 处理 | PostCSS + Autoprefixer |
+| JS 压缩 | Terser |
+| HTML 压缩 | html-minifier-terser |
+| AST 处理 | @babel/* |
+| 文件匹配 | fast-glob |
+| WebSocket | ws |
+
+## 快速开始
+
+### 安装
+
+```bash
+bun install -g @love-sqjm/magic
+```
+
+### 创建项目
+
+```bash
+magic init new-project --web
+```
+
+### 构建项目
+
+```bash
+cd new-project
+magic build
+```
+
+### 运行项目
+
+```bash
+magic run
+```
+
+## 支持的平台
+
+| 平台 | 说明 |
+|------|------|
+| `web` | 浏览器环境，支持内置 HTTP 服务器和热更新 |
+| `node-webkit` | Node-Webkit 桌面应用 |
+| `module` | 可复用的模块库 |
+
+## 项目结构
+
+```
+magic-project/
+├── app/                    # 源码目录
+│   ├── app.xml            # 应用配置文件
+│   ├── index.m           # 入口模块
+│   └── ...                # 其他 .m 模块文件
+├── build/                 # 构建输出目录
+├── build.toml            # 构建配置文件
+└── package.json
+```
+
+## 学习资源
+
+- [架构文档](./architecture.md) - 系统架构和技术细节
+- [使用指南](./user-guide/index.md) - 环境配置和部署步骤
+- [.m 文件规范](./magic-file/index.md) - 组件开发文档
+- [API 参考](./api/index.md) - Runtime API 详细说明
+- [配置手册](./config-reference.md) - build.toml 配置详解
+
+## 许可证
+
+MIT License - [SQJM](https://github.com/SQJM)

package/app.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+
+const runDir = import.meta.dir + '/';
+
+const App = {
+    version : JSON.parse( fs.readFileSync( runDir + "package.json" ).toString() ).version,
+    runDir : runDir,
+    templateDir : {
+        runtime : {
+            path : runDir + "template/runtime/"
+        },
+        platformConfig : {
+            path : runDir + "template/platform-config/"
+        },
+        projectBase : {
+            path : runDir + "template/project-base/"
+        }
+    },
+    project : {
+        dir : process.cwd() + '/'
+    }
+};
+
+function read( path ) {
+    if ( !fs.existsSync( path ) ) throw `${ path } doesn't exist`;
+    return fs.readFileSync( path ).toString();
+}
+
+export const app = {
+    ...App,
+    templateDir : {
+        runtime : {
+            path : App.templateDir.runtime.path,
+            get( fileName ) {
+                return read( App.templateDir.runtime.path + fileName );
+            }
+        },
+        platformConfig : {
+            path : App.templateDir.platformConfig.path,
+            get( fileName ) {
+                return read( App.templateDir.platformConfig.path + fileName );
+            }
+        },
+        projectBase : {
+            path : App.templateDir.projectBase.path,
+            get( fileName ) {
+                return read( App.templateDir.projectBase.path + fileName );
+            }
+        }
+    }
+}

package/doc/api/examples.md

@@ -0,0 +1,563 @@
+# Magic Runtime 函数使用示例
+
+## 目录
+
+1. [模块导入 - importM](#1-模块导入---importm)
+2. [元素获取 - $id / $](#2-元素获取---id--)
+3. [UiData 响应式数据 - createUiData](#3-uodata-响应式数据---createuodata)
+4. [动态值绑定 - DynamicValueBind](#4-动态值绑定---dynamicvaluebind)
+5. [事件系统 - emit / on_event](#5-事件系统---emit--on_event)
+6. [参数处理 - parserArgs / createArgs](#6-参数处理---parserargs--createargs)
+7. [路由系统 - router](#7-路由系统---router)
+8. [其他工具函数](#8-其他工具函数)
+
+---
+
+## 1. 模块导入 - importM
+
+### 基本用法
+
+```javascript
+// 导入并实例化一个组件
+const dialog = magic.importM("dialog");
+
+// 传入参数
+const form = magic.importM("form", {
+    title: "用户注册",
+    width: 400
+});
+
+// 传入事件监听
+const button = magic.importM("button", {}, {
+    click: (data) => {
+        console.log("按钮被点击:", data);
+    }
+});
+```
+
+### 完整示例
+
+```xml
+<!-- button.m -->
+<template>
+    <button #id="btn">点击</button>
+</template>
+
+<script code="event">
+click = (event) => {
+    emit_event("click", { time: Date.now() });
+}
+</script>
+
+<script code="interface">
+setText = (text) => {
+    $btn.textContent = text;
+};
+</script>
+```
+
+```javascript
+// 使用按钮组件
+const btn = magic.importM("button");
+btn.interface.setText("新文本");
+```
+
+---
+
+## 2. 元素获取 - $id / $
+
+### $id() - 获取模块内元素
+
+```xml
+<script code="global">
+const {
+    $container,    // 获取 #id="container" 的元素
+    $title,        // 获取 #id="title" 的元素
+    $submitBtn     // 获取 #id="submitBtn" 的元素
+} = $id();
+</script>
+```
+
+### $() - 全局查询
+
+```javascript
+// 在整个文档中查找元素
+const element = magic.$("my-element-id");
+
+// 在指定根元素内查找
+const container = magic.$("container-id");
+const child = magic.$("child-id", container);
+```
+
+### 查找命名元素
+
+```xml
+<template>
+    <div #id="form">
+        <input #name="username" placeholder="用户名"/>
+        <button #name="submit">提交</button>
+    </div>
+</template>
+
+<script code="global">
+const { $form } = $id();
+
+// 使用 $name 查找命名元素
+const usernameInput = $form.$name("username");
+const submitBtn = $form.$name("submit");
+</script>
+```
+
+---
+
+## 3. UiData 响应式数据 - createUiData
+
+### 基本用法
+
+```xml
+<script code="global">
+const UiData = magic_define_ui_data({
+    username: "Guest",
+    age: 18,
+    isActive: true
+});
+
+// 修改值会自动触发更新
+UiData.username = "Alice";
+UiData.age = 25;
+UiData.isActive = false;
+</script>
+```
+
+### 嵌套对象
+
+```xml
+<script code="global">
+const UiData = magic_define_ui_data({
+    user: {
+        name: "Guest",
+        profile: {
+            avatar: "",
+            bio: ""
+        }
+    }
+});
+
+// 深度修改
+UiData.user.name = "Alice";
+UiData.user.profile.avatar = "/avatar.png";
+</script>
+```
+
+### 数组支持
+
+```xml
+<script code="global">
+const UiData = magic_define_ui_data({
+    items: ["苹果", "香蕉", "橙子"],
+    selectedIndex: 0
+});
+
+// 修改数组
+UiData.items.push("葡萄");
+UiData.selectedIndex = 2;
+</script>
+```
+
+### 类型自动转换
+
+```xml
+<script code="global">
+const UiData = magic_define_ui_data({
+    count: 0,           // Number
+    isValid: false,      // Boolean
+    pattern: /^abc$/,    // RegExp
+    data: [1, 2, 3]     // Array
+});
+
+// 传入字符串会自动转换类型
+const UserInput = magic.createUiData(UiData, {
+    count: "42",           // "42" → 42
+    isValid: "true",      // "true" → true
+    pattern: "/^xyz$/",   // 字符串 → RegExp
+    data: "[1,2,3,4]"     // 字符串 → Array
+});
+</script>
+```
+
+---
+
+## 4. 动态值绑定 - DynamicValueBind
+
+### 文本节点绑定
+
+```xml
+<template>
+    <div #id="container">
+        <p #id="name-text">Hello ${username}</p>
+        <p #id="count-text">Count: ${count}</p>
+    </div>
+</template>
+
+<script code="global">
+const UiData = magic_define_ui_data({
+    username: "Guest",
+    count: 0
+});
+
+const {
+    $nameText,
+    $countText
+} = $id();
+</script>
+
+<script code="interface">
+startBinding = () => {
+    magic_dynamic_value_bind($nameText, $countText);
+};
+
+increment = () => {
+    UiData.count++;
+};
+</script>
+
+<script>
+startBinding();
+</script>
+```
+
+### 工作原理
+
+1. `${username}` 在编译时被转换为注释节点 `<!--MAGIC:DV[username]-->`
+2. `magic_dynamic_value_bind()` 找到所有绑定点
+3. 当 `UiData.username` 改变时，文本节点自动更新
+
+---
+
+## 5. 事件系统 - emit / on_event
+
+### 定义事件
+
+```xml
+<template>
+    <button #id="btn">点击</button>
+</template>
+
+<expose-event>
+    <click/>
+    <change/>
+</expose-event>
+
+<script code="event">
+click = (eventData) => {
+    emit_event("click", { timestamp: Date.now() });
+};
+
+change = (newValue) => {
+    emit_event("change", { value: newValue });
+};
+</script>
+```
+
+### 监听事件
+
+```javascript
+const component = magic.importM("my-component", {}, {
+    click: (data) => {
+        console.log("点击事件:", data);
+    },
+    change: (data) => {
+        console.log("变更事件:", data);
+    }
+});
+```
+
+### 主动触发事件
+
+```javascript
+// 通过 call 接口触发
+const scope = magic.call(component);
+scope.event("click", { custom: true });
+```
+
+---
+
+## 6. 参数处理 - parserArgs / createArgs
+
+### parserArgs - 解析参数
+
+```javascript
+// 解析 JSON 字符串
+const args1 = magic.parserArgs('{"name":"Alice","age":25}');
+// 结果: { name: "Alice", age: 25 }
+
+// 解析嵌套键
+const args2 = magic.parserArgs({
+    "user:profile:name": "Alice",
+    "user:profile:age": "25"
+});
+// 结果: { user: { profile: { name: "Alice", age: "25" } } }
+
+// 使用冒号分隔的键
+const args3 = magic.parserArgs({
+    "a:b:c": "deep value"
+});
+// 结果: { a: { b: { c: "deep value" } } }
+```
+
+### createArgs - 创建参数字符串
+
+```javascript
+const obj = { name: "Alice", age: 25 };
+const jsonStr = magic.createArgs(obj);
+// 结果: '{"name":"Alice","age":25}'
+```
+
+---
+
+## 7. 路由系统 - router
+
+### 基本使用
+
+```javascript
+// 添加路由
+magic.router.addRoute('/', 'home');
+magic.router.addRoute('/about', 'about');
+magic.router.addRoute('/user/:id', 'user-profile');
+
+// 初始化路由
+magic.router.init('router-view');
+```
+
+### 批量添加路由
+
+```javascript
+magic.router.addRoutes([
+    { path: '/', component: 'home' },
+    { path: '/about', component: 'about' },
+    { path: '/user/:id', component: 'user-profile' },
+    { path: '/post/:postId/comment/:commentId', component: 'comment' }
+]);
+```
+
+### 导航
+
+```javascript
+// 跳转到新路径（添加历史记录）
+magic.router.push('/about');
+
+// 替换当前路径（不添加历史）
+magic.router.replace('/user/123');
+
+// 获取当前路由
+const route = magic.router.getCurrentRoute();
+console.log(route.path);      // "/user/123"
+console.log(route.params.id); // "123"
+console.log(route.query);    // { search: "abc" }
+```
+
+### 动态路由参数
+
+```javascript
+// /user/:id → { path: '/user/123', params: { id: '123' } }
+// /post/:postId/comment/:commentId → { path: '/post/1/comment/5', params: { postId: '1', commentId: '5' } }
+```
+
+### 导航守卫
+
+```javascript
+magic.router.beforeEach((to, from) => {
+    // to: 目标路由信息
+    // from: 来源路由信息
+
+    if (to.path === '/admin' && !isLoggedIn) {
+        return '/login'; // 重定向到登录页
+    }
+
+    return true; // 允许导航
+});
+
+// 支持异步守卫
+magic.router.beforeEach(async (to, from) => {
+    const canAccess = await checkPermission(to.path);
+    if (!canAccess) {
+        return '/unauthorized';
+    }
+    return true;
+});
+```
+
+### 完整示例
+
+```xml
+<!-- index.m -->
+<template>
+    <div #id="app">
+        <nav #id="nav">
+            <a @click="goHome">首页</a>
+            <a @click="goAbout">关于</a>
+            <a @click="goUser">用户:123</a>
+        </nav>
+        <div #id="router-view"></div>
+    </div>
+</template>
+
+<script code="event">
+goHome = () => magic.router.push('/');
+goAbout = () => magic.router.push('/about');
+goUser = () => magic.router.push('/user/123');
+</script>
+
+<script>
+magic.router.addRoutes([
+    { path: '/', component: 'home' },
+    { path: '/about', component: 'about' },
+    { path: '/user/:id', component: 'user-profile' }
+]);
+
+magic.router.init('router-view');
+</script>
+```
+
+---
+
+## 8. 其他工具函数
+
+### importElementInit - 初始化导入组件
+
+```javascript
+// 导入多个组件并批量初始化
+magic.importElementInit(comp1, comp2, comp3);
+// 会依次调用每个组件的 _render() 接口方法
+```
+
+### exportInterface - 导出接口
+
+```javascript
+const target = {};
+magic.exportInterface(scope, target, {
+    _render: nop,           // 直接映射
+    onClick: (args) => {   // 函数转换
+        console.log("Clicked with:", args);
+    }
+});
+```
+
+### GetInterface - 获取组件接口
+
+```javascript
+const element = magic.$("my-component");
+const interface = magic.GetInterface(element);
+if (interface) {
+    interface.someMethod();
+}
+```
+
+### BindScope - 绑定作用域
+
+```javascript
+const elements = [elem1, elem2, elem3];
+const scoped = magic.BindScope(elements, scope);
+// 每个元素会添加 __SCOPE__ 属性指向 scope
+```
+
+### mapIdElement - ID 映射
+
+```javascript
+const map = magic.mapIdElement();
+map.s("element-id", element, "optional-class");
+const el = map.get("element-id");
+```
+
+### idGenerate - 生成唯一 ID
+
+```javascript
+const id1 = magic.idGenerate(); // 生成带时间戳的唯一 ID
+const id2 = magic.idGenerate(6); // 指定长度
+```
+
+### parserListen - 解析监听器
+
+```javascript
+const listen = magic.parserListen({
+    click: handleClick,
+    change: handleChange
+});
+```
+
+---
+
+## 综合示例：完整组件
+
+```xml
+<!-- user-card.m -->
+<import root=".">
+    <avatar/>
+</import>
+
+<template>
+    <div #id="card">
+        <avatar #id="avatar-img" :src="avatar"/>
+        <h3 #id="name">${name}</h3>
+        <p #id="bio">${bio}</p>
+        <button #id="edit-btn" @click="edit">编辑</button>
+    </div>
+</template>
+
+<script code="global">
+const UiData = magic_define_ui_data({
+    name: "未命名",
+    bio: "暂无简介",
+    avatar: "/default-avatar.png"
+});
+
+const { $name, $bio } = $id();
+</script>
+
+<expose-event>
+    <edit/>
+</expose-event>
+
+<script code="event">
+edit = () => {
+    emit_event("edit", { name: UiData.name });
+};
+</script>
+
+<script code="interface" once>
+init = () => {
+    magic_dynamic_value_bind($name, $bio);
+};
+
+setUser = (user) => {
+    UiData.name = user.name;
+    UiData.bio = user.bio;
+    if (user.avatar) UiData.avatar = user.avatar;
+};
+
+getUser = () => {
+    return {
+        name: UiData.name,
+        bio: UiData.bio
+    };
+};
+</script>
+
+<script code="interface">
+startBinding();
+</script>
+```
+
+**使用:**
+
+```javascript
+const card = magic.importM("user-card");
+
+card.interface.setUser({
+    name: "Alice",
+    bio: "一名前端开发者",
+    avatar: "/avatars/alice.png"
+});
+
+card.interface.getUser(); // { name: "Alice", bio: "一名前端开发者" }
+```