zc-lowcode 0.0.3 → 0.0.4

package/README.md

@@ -1,26 +1,43 @@
-# @fp-mall/lowcode
+# zc-lowcode
 
-面向 fp-mall 的可视化页面搭建 SDK。提供 **设计器（Designer）** 与 **运行时（Runtime）** 两套入口，共享同一套页面 JSON 契约（`Page` / `Widget` 树）。
+可视化页面搭建 SDK，提供 **设计器（Designer）** 与 **运行时（Runtime）** 两套入口，共享同一套页面 JSON 契约（`Page` / `Widget` 树）。
+
+## 安装
+
+```bash
+npm install zc-lowcode
+# 或
+pnpm add zc-lowcode
+# 或
+yarn add zc-lowcode
+```
+
+依赖：`vue ^3.5`（peer）、`ant-design-vue`（设计器 UI）、`vuedraggable`（画布拖拽）。
 
 ## 包结构
 
 ```
-packages/lowcode/
+code/
 ├── src/
-│   ├── engine/              # 核心引擎（无 UI 壳）
-│   │   ├── core/            # Page/Widget 类型、物料注册、页面脚本、快照、表达式
-│   │   └── context/         # 注入 Key、主题 token、对外 props 类型、fetch 适配器
+│   ├── core/                # 核心引擎（无 UI 壳）
+│   │   └── index.ts         # Page/Widget 类型、物料注册、快照、命令、历史
 │   ├── materials/           # 内置物料（button、grid、tab 等）
+│   │   ├── packages/        # 各物料实现（view / setter / designer）
+│   │   ├── page/            # 页面根节点物料
+│   │   ├── shared/          # 属性面板、设计态公共组件
 │   │   ├── definitions.ts   # 设计器全量 materialDefinitions
-│   │   └── runtime-definitions.ts  # 由 definitions 自动生成的运行时轻量副本
+│   │   └── runtime-definitions.ts  # 仅 view 的运行时轻量副本
 │   ├── designer/            # 可视化设计器 UI
-│   │   ├── core/            # createDesigner、设计器物料注册表
-│   │   ├── shell/           # LowcodeDesigner 主壳与侧栏
+│   │   ├── designer.ts      # createDesigner、撤销/重做
+│   │   ├── material-registry.ts  # 设计器物料注册表
 │   │   ├── canvas/          # 画布、拖拽、选中框
-│   │   ├── setter/          # 属性面板与通用表单组件
-│   │   ├── page/            # 页面 data/methods/lifecycle 编辑器
-│   │   └── context/         # 设计器 ConfigProvider、inject 辅助
+│   │   ├── properties/      # 属性面板
+│   │   ├── outline/         # 大纲
+│   │   ├── datasource/      # 数据源编辑
+│   │   └── methods/         # 页面函数 / 接口配置
 │   └── runtime/             # LowcodePageRenderer 页面渲染器
+│       ├── runtime.ts       # 生命周期、事件、样式、注入键
+│       └── widget-node.vue  # 运行时组件树递归
 ├── uno.config.ts            # UnoCSS 配置（runtime / designer 分 scope）
 └── vite.config.ts           # 多入口 lib 构建
 ```
@@ -29,25 +46,24 @@ packages/lowcode/
 
 | 模块 | 职责 | 典型导出 |
 | --- | --- | --- |
-| `engine` | 类型契约、物料注册表、页面脚本执行、快照序列化 | `Page`、`clonePageSnapshot`、`useLifecycle` |
+| `core` | 类型契约、物料注册表、页面树操作、快照序列化 | `Page`、`clonePageSnapshot`、`createMaterialRegistry` |
 | `materials` | 内置物料元数据与 palette 分组 | `materialDefinitions`、`runtimeMaterialDefinitions` |
 | `designer` | 可视化编辑 UI | `LowcodeDesigner`、`createDesigner` |
-| `runtime` | 运行时页面渲染 | `LowcodePageRenderer` |
+| `runtime` | 运行时页面渲染 | `LowcodePageRenderer`、`useLifecycle` |
 
 ## 子包入口
 
 | 入口 | 用途 |
 | --- | --- |
-| `@fp-mall/lowcode/engine` | 类型、快照工具、页面脚本 API，无 Vue 组件 |
-| `@fp-mall/lowcode/materials` | 全量物料定义 `materialDefinitions`、默认注册表 |
-| `@fp-mall/lowcode/designer` | `LowcodeDesigner` 设计器组件 |
-| `@fp-mall/lowcode/runtime` | `LowcodePageRenderer` 运行时渲染器 |
-| `@fp-mall/lowcode/style` | 运行时样式副作用入口 |
-| `@fp-mall/lowcode/style/designer` | 设计器样式副作用入口 |
-| `@fp-mall/lowcode/style/runtime` | 同 `style` |
-| `@fp-mall/lowcode/uno.config` | 供消费方扩展 UnoCSS 的基准配置 |
-
-依赖：`vue ^3.5`（peer）、`ant-design-vue`（设计器 UI）、`vuedraggable`（画布拖拽）。
+| `zc-lowcode/core` | 类型、快照工具、物料注册表，无 Vue 组件 |
+| `zc-lowcode/materials` | 全量物料定义 `materialDefinitions`、默认注册表 |
+| `zc-lowcode/designer` | `LowcodeDesigner` 设计器组件 |
+| `zc-lowcode/runtime` | `LowcodePageRenderer` 运行时渲染器 |
+| `zc-lowcode/style` | 运行时样式副作用入口 |
+| `zc-lowcode/style/designer` | 设计器样式副作用入口 |
+| `zc-lowcode/style/runtime` | 同 `style` |
+| `zc-lowcode/style/materials` | 物料相关样式副作用入口 |
+| `zc-lowcode/uno.config` | 供消费方扩展 UnoCSS 的基准配置 |
 
 ---
 
@@ -57,9 +73,8 @@ packages/lowcode/
 
 - **Page** 是页面根节点，`type: 'page'`，除通用 Widget 字段外还包含：
   - `data` — 页面初始数据（设计器可编辑）
-  - `methods` — 页面自定义函数（含 async fetch 请求）
+  - `methods` — 页面自定义函数（支持 API 模板生成 fetch 请求）
   - `lifecycle` — 生命周期钩子源码
-  - `methods` — 自定义方法列表
 - **Widget** = **可持久化字段**（`WidgetPersisted`）+ **仅设计态字段**（`WidgetEditorFields`）。
 
 可持久化字段（入库 / 历史快照 / `v-model` 出站）：
@@ -107,26 +122,24 @@ type MaterialDefinition = {
 
 ## 快速接入
 
-### 设计器（Admin 微页面等）
+### 设计器
 
 ```vue
 <script setup lang="ts">
 import {
   LowcodeDesigner,
   createDefaultPage,
-  type LowcodeFetchAdapter,
+  type LowcodeUploadHandler,
   type Page
-} from '@fp-mall/lowcode/designer'
-import { materialDefinitions } from '@fp-mall/lowcode/materials'
-import '@fp-mall/lowcode/style/designer'
+} from 'zc-lowcode/designer'
+import { materialDefinitions } from 'zc-lowcode/materials'
+import 'zc-lowcode/style/designer'
 
 const page = ref<Page>(createDefaultPage())
 
-const fetchAdapter: LowcodeFetchAdapter = {
-  async request(req) {
-    // 对接宿主 HTTP 客户端；页面接口、图片上传等均通过此适配器
-    return { ok: true, status: 200, data: /* ... */ }
-  }
+const uploadHandler: LowcodeUploadHandler = async ({ file }) => {
+  // 对接宿主上传接口，返回图片 URL
+  return 'https://example.com/uploaded.png'
 }
 </script>
 
@@ -134,7 +147,7 @@ const fetchAdapter: LowcodeFetchAdapter = {
   <LowcodeDesigner
     v-model:page="page"
     :definitions="materialDefinitions"
-    :fetch-adapter="fetchAdapter"
+    :upload-handler="uploadHandler"
     :theme="theme"
     :locale="locale"
   />
@@ -145,18 +158,16 @@ const fetchAdapter: LowcodeFetchAdapter = {
 
 - **必须** 传入 `:definitions`（通常用 `materialDefinitions`）。
 - 通过 `v-model:page` 双向绑定；出站数据已是剥离编辑态字段的快照。
-- `fetchAdapter` 用于页面 API、Setter 内图片上传等网络请求。
+- `uploadHandler` 用于 Setter 内图片上传等场景。
 - `theme` / `locale` 与 Ant Design Vue `ConfigProvider` 一致。
 
-参考：`admin/src/pages/setting/micropages/edit/index.vue`。
-
-### 运行时（Portal 等）
+### 运行时
 
 ```vue
 <script setup lang="ts">
-import { LowcodePageRenderer, type Page } from '@fp-mall/lowcode/runtime'
-import { clonePageSnapshot } from '@fp-mall/lowcode/engine'
-import '@fp-mall/lowcode/style'
+import { LowcodePageRenderer, type Page } from 'zc-lowcode/runtime'
+import { clonePageSnapshot } from 'zc-lowcode/core'
+import 'zc-lowcode/style'
 
 const page = ref<Page>(/* 从接口加载的 JSON */)
 
@@ -166,7 +177,6 @@ const page = ref<Page>(/* 从接口加载的 JSON */)
 <template>
   <LowcodePageRenderer
     :page="page"
-    :fetch-adapter="fetchAdapter"
     :theme="theme"
     :locale="locale"
   />
@@ -179,8 +189,6 @@ const page = ref<Page>(/* 从接口加载的 JSON */)
 - 也可传入自定义 `:definitions`，须保证 `type` 与持久化 JSON 一致。
 - **不要** 把带 `component` / `setterComponent` 的设计态 JSON 原样落库；服务端存 `clonePageSnapshot` 结果即可。
 
-参考：`portal/app/pages/index.vue`（开发阶段可能内联 page JSON，生产应从接口读取）。
-
 ---
 
 ## 页面脚本
@@ -190,7 +198,7 @@ Page 级脚本能力由 `useLifecycle` 驱动，设计器与运行时共用实
 | 能力 | 字段 | 说明 |
 | --- | --- | --- |
 | 数据 | `page.data` | `PageDataItem[]`，编译为 `context.data` |
-| 方法 | `page.methods` | 可绑定到组件事件与 `{{ }}`；HTTP 请求通过 async 函数 + fetch 实现 |
+| 方法 | `page.methods` | 可绑定到组件事件与 `{{ }}`；支持手写脚本或 API 模板（生成 fetch 请求） |
 | 生命周期 | `page.lifecycle` | `beforeMount`、`mounted` 等 |
 
 运行时上下文 `PageScriptContext`：
@@ -223,7 +231,7 @@ View 组件内通过 `useWidgetEvents` 获取 `domEventHandlers`，挂到根元
 每个物料建议目录结构：
 
 ```
-src/materials/{type}/
+src/materials/packages/{type}/
 ├── index.ts       # Widget 元数据 + 导出
 ├── options.ts     # 类型、默认值、ensureXxxOptions、样式/布局工具
 ├── view.vue       # 运行时 & 无 designer 时的画布渲染
@@ -238,8 +246,8 @@ src/materials/{type}/
 import View from './view.vue'
 import Setter from './setter.vue'
 import Icon from './icon.svg'
-import type { Widget } from '../../engine/core/widget-base.ts'
-import { COMMON_CONTAINER_EVENT_PRESETS } from '../../engine/core/event-presets.ts'
+import type { Widget } from '../../../core/index.ts'
+import { COMMON_CONTAINER_EVENT_PRESETS } from '../../../core/index.ts'
 import { ensureMyOptions } from './options.ts'
 
 const widget: Widget = {
@@ -281,7 +289,7 @@ export default widget
 在 `src/materials/definitions.ts` 追加：
 
 ```ts
-import myWidget from './my-widget/index.ts'
+import myWidget from './packages/my-widget/index.ts'
 
 export const materialDefinitions: MaterialDefinition[] = [
   // ...
@@ -308,7 +316,7 @@ export const materialDefinitions: MaterialDefinition[] = [
 - 子项挂在 `container.children`，由 `options.activeKey` 控制当前项
 - 配置 `keyedSlotConfig` + `normalize` + 通常 `copyNeedsNormalize: true`
 
-推荐使用 `createKeyedSlotMaterialHelpers`（`engine/core/keyed-slot.ts`）生成：
+推荐使用 `createKeyedSlotMaterialHelpers`（`runtime/runtime.ts`）生成：
 
 - `keyedSlotConfig`
 - `normalizeWidget`
@@ -329,7 +337,7 @@ View 通过 `<slot name="item" :item :index :visible />` 暴露子项；`widget-
 ## 设计器架构要点
 
 - `createDesigner()` 管理页面树、选中态、撤销/重做（快照栈，默认 20 步，350ms 防抖）。
-- `createDesignerMaterialRegistry()` 在 engine 注册表上扩展 palette 分组与设计态组件解析。
+- `createDesignerMaterialRegistry()` 在 core 注册表上扩展 palette 分组与设计态组件解析。
 - 画布：`DesignerWidgetNode` → 有 `designerComponent` 则渲染设计外壳，否则渲染 view；运行时递归渲染在 `widget-node.vue`（内部组件，不对外导出）中，与设计器共享 `useWidgetNodeContext`。
 - 外部 `v-model:page` 变更会 `loadPage`；内部编辑会 `clonePageSnapshot` 回写，避免编辑态字段泄漏。
 
@@ -340,7 +348,7 @@ View 通过 `<slot name="item" :item :index :visible />` 暴露子项；`widget-
 | `DESIGNER_KEY` | 设计器实例 |
 | `MATERIAL_REGISTRY_KEY` | 物料注册表（可用 `useMaterialRegistry()` 注入） |
 | `LOWCODE_DESIGN_MODE_KEY` | 是否设计模式 |
-| `LOWCODE_FETCH_KEY` | HTTP 适配器 |
+| `LOWCODE_UPLOAD_KEY` | 图片上传 handler |
 | `LIFECYCLE_KEY` | 页面脚本运行时 |
 
 ---
@@ -360,14 +368,13 @@ View 通过 `<slot name="item" :item :index :visible />` 暴露子项；`widget-
 
 | 路径 | 约定 |
 | --- | --- |
-| `engine/core/page-script.ts` | 页面脚本运行时（data/methods/lifecycle/events），勿与 `src/runtime/` 混淆 |
-| `engine/core/material.ts` | 物料注册表与组件名解析 |
-| `designer/core/designer-material-registry.ts` | 设计器物料注册表（palette 分组、设计态 view 解析） |
-| `designer/page/page-editor-presets.ts` | 页面编辑器 UI 预设文案（非 Page options schema） |
-| `materials/{type}/options.ts` | 物料 options 类型与默认值 |
-| `materials/{type}/view.vue` | 运行时 view |
-| `materials/{type}/setter.vue` | 属性面板 |
-| `materials/{type}/designer.vue` | 可选设计态外壳 |
+| `core/index.ts` | 核心模型、物料注册、快照、命令、历史 |
+| `runtime/runtime.ts` | 页面脚本运行时、事件、样式、注入键 |
+| `designer/material-registry.ts` | 设计器物料注册表（palette 分组、设计态 view 解析） |
+| `materials/packages/{type}/options.ts` | 物料 options 类型与默认值 |
+| `materials/packages/{type}/view.vue` | 运行时 view |
+| `materials/packages/{type}/setter.vue` | 属性面板 |
+| `materials/packages/{type}/designer.vue` | 可选设计态外壳 |
 
 ### 数据与 API 命名
 
@@ -381,21 +388,22 @@ View 通过 `<slot name="item" :item :index :visible />` 暴露子项；`widget-
 
 ---
 
-## 构建与开发
+## 构建与发布
 
 ```bash
-# 在 monorepo 根目录或 packages/lowcode 下
-pnpm --filter @fp-mall/lowcode build   # 生产构建 → dist/
-pnpm --filter @fp-mall/lowcode dev     # watch 模式
+# 在 code/ 目录下
+npm run build    # 生产构建 → dist/
+npm run dev      # watch 模式
+npm run release  # build + 发布到 npm（需先 npm login）
 ```
 
 构建产物：
 
-- `dist/engine.js`、`dist/materials.js`、`dist/designer.js`、`dist/runtime.js`
+- `dist/core.js`、`dist/materials.js`、`dist/designer.js`、`dist/runtime.js`
 - 对应 `.d.ts` 与 CSS 资源
 - `designer.d.ts` / `runtime.d.ts` 为 Vue 组件类型 shim
 
-修改物料或引擎后需重新 build，Admin / Portal 才能引用最新 dist。
+修改物料或引擎后需重新 build，消费方才能引用最新 dist。
 
 ---
 
@@ -404,11 +412,10 @@ pnpm --filter @fp-mall/lowcode dev     # watch 模式
 | type | 名称 | 分组 | 说明 |
 | --- | --- | --- | --- |
 | `grid` | 容器 | 容器组件 | 支持结构化行列布局 |
-| `section` | 区块 | 容器组件 | |
 | `card` | 卡片 | 容器组件 | |
 | `tab` | 标签页 | 容器组件 | Keyed Slot，子类型 `tab-pane` |
 | `carousel` | 走马灯 | 容器组件 | Keyed Slot，子类型 `carousel-slide` |
-| `list` | 列表 | 容器组件 | 循环渲染，子类型 `list-item` |
+| `list` | 列表 | 容器组件 | 绑定数据源循环渲染 |
 | `button` | 按钮 | 基础组件 | |
 | `image` | 图片 | 基础组件 | |
 | `text` | 文本 | 基础组件 | |
@@ -426,7 +433,7 @@ A: 不要。始终用 `clonePageSnapshot` / `serializePageSnapshot` 出站；运
 A: `type` 必须与持久化 JSON 一致；运行时只需 view 链，可不含 setter/designer，体积更小。
 
 **Q: 如何扩展页面 HTTP？**  
-A: HTTP 请求在 `page.methods` 中编写 async 函数，通过 `fetch` 实现，在生命周期或事件中 `await context.methods.xxx(...)` 调用。
+A: 在设计器「函数」面板使用 API 模板配置请求，或手写 `page.methods` 中的 async 函数（内部使用 `fetch`），在生命周期或事件中 `await context.methods.xxx(...)` 调用。
 
 **Q: 复制 tab/carousel 后子项错乱？**  
 A: 容器 Widget 应设置 `copyNeedsNormalize: true` 并提供 `normalize`，复制后会重新分配 id 并规范化子树。

package/package.json

@@ -8,7 +8,7 @@
     "lowcode",
     "lowcode-editor"
   ],
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "sideEffects": [
     "**/*.css",