mail-editor-pancake 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # Simple Mail Editor
 
-面向运营的轻量邮件可视化编辑器（产品名 **Simple Mail**）。聚焦邮件场景，用**严格扁平化的组件树** + **MJML 输出引擎**，解决 GrapesJS 在邮件场景下「任意嵌套 → 拖拽混乱 → 文本组件消失」的痛点。
+**Simple Mail** 是面向运营与开发的轻量邮件可视化编辑器。文档模型固定为四层（Doc → Section → Column → Block），导出链路为 JSON → MJML → HTML，可嵌入 React、Vue 或任意前端项目。
 
 ```text
 Doc → Section → Column → Block    // 仅四层，Block 不可再嵌套子组件
@@ -9,7 +9,7 @@ Doc → Section → Column → Block    // 仅四层，Block 不可再嵌套子
 
 ## 目录
 
-- [命名与 npm 包](#命名与-npm-包)
+- [npm 包](#npm-包)
 - [特性](#特性)
 - [仓库结构](#仓库结构)
 - [开发与构建](#开发与构建)
@@ -26,7 +26,7 @@ Doc → Section → Column → Block    // 仅四层，Block 不可再嵌套子
 - [图片资源 `imageAssets`](#图片资源-imageassets)
 - [框架集成示例](#框架集成示例)
 - [自定义组件](#自定义组件)
-- [宿主集成注意](#宿主集成注意)
+- [集成说明](#集成说明)
 - [操作手册](#操作手册)
 - [设计与代码模式](#设计与代码模式)
 - [数据模型速览](#数据模型速览)
@@ -36,26 +36,18 @@ Doc → Section → Column → Block    // 仅四层，Block 不可再嵌套子
 
 ---
 
-## 命名与 npm 包
+## npm 包
 
-三层名称各司其职，**不必强行统一成一个字符串**：
+安装与业务代码中的 import 使用下列 **scoped 包名**：
 
-| 层级 | 名称 | 说明 |
-|------|------|------|
-| 仓库目录 | `simple-mail` | Git 路径、内部日志前缀（`[simple-mail]`）、剪贴板 kind（`simple-mail/doc`）、引擎标识等 |
-| 对外子包 | `@simple-mail/core`、`@simple-mail/blocks` | **业务代码应使用的 import 名**；发布到 npm 的主包 |
-| Monorepo 根 | `mail-editor-pancake` | 无 scope 的 `simple-mail` 在 npm 已被占用时的根包名；适合 `pnpm link` 整仓，**不作为对外 API 文档的安装名** |
+| 包名 | 内容 |
+|------|------|
+| `@simple-mail/core` | 编辑器引擎、`MailEditor`、类型与工具函数；样式入口 `@simple-mail/core/style.css` |
+| `@simple-mail/blocks` | 内置组件与示例自定义块（`builtinBlocks`、`allBlocks`） |
 
-```text
-simple-mail/                    # 仓库根（package.json name: mail-editor-pancake）
-├── packages/
-│   ├── core/    →  @simple-mail/core
-│   └── blocks/  →  @simple-mail/blocks
-└── playground/
-    └── vanilla/ →  @simple-mail/playground-vanilla（本地演示，不发布）
-```
+本仓库在 Git 中目录名为 `simple-mail`；npm 上 monorepo 根包名为 `mail-editor-pancake`（因无 scope 的 `simple-mail` 已被占用）。**集成时请只安装并 import `@simple-mail/*`**，不要依赖 `mail-editor-pancake/packages/...` 这类深路径。
 
-**推荐写法（npm 或 link 后统一用 scope）：**
+本地 link 整仓开发时，依赖名可能为 `mail-editor-pancake`，但代码中仍应写 `@simple-mail/core` 等，并在构建工具里配置 alias（见 [安装与集成](#安装与集成)）。
 
 ```ts
 import { MailEditor } from '@simple-mail/core';
@@ -63,7 +55,14 @@ import '@simple-mail/core/style.css';
 import { allBlocks } from '@simple-mail/blocks';
 ```
 
-不推荐长期依赖 `mail-editor-pancake/packages/core` 深路径；若宿主已 link 根包，请在 Vite alias 中把 `@simple-mail/*` 指到 `node_modules/mail-editor-pancake/packages/*`（见 [安装与集成](#安装与集成)）。
+仓库目录结构：
+
+```text
+simple-mail/
+├── packages/core/    →  @simple-mail/core
+├── packages/blocks/  →  @simple-mail/blocks
+└── playground/vanilla/   演示项目（不随 npm 发布）
+```
 
 ---
 
@@ -83,7 +82,7 @@ import { allBlocks } from '@simple-mail/blocks';
 - **仅搭正文**：`ui.hideMailMeta` 隐藏主题、Preheader 与顶栏「邮件设置」
 - **清空 / 重置**：`presetDoc` 与 `initialDoc` 分离
 - **变量系统**：`setVariables`；`kind: link | image`；顶栏 `{{ }}` 弹层
-- **动态变量节**（可选）：`Section.attrs.dynamicVariantKey`，导出时整节替换为 `{{key}}`，由宿主填充（券包等）
+- **动态变量节**（可选）：`Section.attrs.dynamicVariantKey`，导出时整节替换为 `{{key}}`，由业务侧注入最终 HTML（如券包区块）
 - **点空白取消选中**：`clearSelectionOnCanvasMargin`
 - 包体：核心 + MJML + CodeMirror + 富文本，gzip ≈ 580–590KB（主要来自 `mjml-browser`）
 
@@ -118,20 +117,21 @@ pnpm lint         # biome check
 pnpm --filter @simple-mail/playground-vanilla build
 ```
 
-修改 `packages/core` 源码后，在 monorepo 根执行 **`pnpm build`**（或 `pnpm --filter @simple-mail/core build`），再让宿主重新加载，避免 link 场景下 `dist` 与源码不一致。
+若你正在本地修改本仓库源码，请在 monorepo 根执行 `pnpm build` 后再刷新引用方项目，以保证 `dist` 与类型声明一致。
 
 ---
 
 ## 安装与集成
 
-### 从 npm 安装（推荐）
+### 从 npm 安装
 
 ```bash
 pnpm add @simple-mail/core @simple-mail/blocks
-# 与 core 同版本传递依赖，宿主需能解析到：
 pnpm add codemirror mjml-browser sortablejs
 ```
 
+`@simple-mail/core` 依赖 CodeMirror、MJML 与 SortableJS，请在项目中一并安装，以便打包工具能正确解析。
+
 ```ts
 import { MailEditor } from '@simple-mail/core';
 import '@simple-mail/core/style.css';
@@ -141,9 +141,9 @@ import { builtinBlocks, allBlocks } from '@simple-mail/blocks';
 - 仅需内置块时用 `builtinBlocks`；需要 Logo/页脚等示例时用 `allBlocks`，或与业务 `defineBlock` 合并。
 - `@simple-mail/blocks` 依赖 `@simple-mail/core`，版本宜对齐。
 
-### 本地 link 整仓（monorepo 开发）
+### 本地 link（参与本仓库开发时）
 
-宿主 `package.json`：
+在你的项目 `package.json` 中 link 本仓库根包，并安装与 core 相同的运行时依赖：
 
 ```json
 {
@@ -159,7 +159,7 @@ import { builtinBlocks, allBlocks } from '@simple-mail/blocks';
 }
 ```
 
-**业务 import 仍使用 `@simple-mail/*`**，在 Vite 中 alias 到 link 后的子包路径，并排除预构建缓存：
+import 路径仍使用 `@simple-mail/*`。以 Vite 为例，将 alias 指向 `node_modules/mail-editor-pancake/packages` 下对应子包，并将这些包排除在依赖预构建之外：
 
 ```ts
 // vite.config.ts 示意
@@ -171,7 +171,7 @@ export default defineConfig({
       '@simple-mail/core': path.join(mailEditorPkgRoot, 'core'),
       '@simple-mail/core/style.css': path.join(mailEditorPkgRoot, 'core/dist/style.css'),
       '@simple-mail/blocks': path.join(mailEditorPkgRoot, 'blocks'),
-      // link 时 dist 内嵌套解析 codemirror / mjml-browser / sortablejs，常需指向宿主 node_modules
+      // link 时建议将 codemirror / mjml-browser / sortablejs 解析到你项目中的安装路径
       codemirror: path.dirname(require.resolve('codemirror/package.json')),
       'mjml-browser': path.dirname(require.resolve('mjml-browser/package.json')),
       sortablejs: path.dirname(require.resolve('sortablejs/package.json')),
@@ -183,7 +183,7 @@ export default defineConfig({
 });
 ```
 
-仍出现「拖拽/组合拖入与源码不符」时：先 `pnpm build`（编辑器仓），再删除宿主 `node_modules/.vite` 并重启 dev。
+若界面行为与最新源码不一致：先在编辑器仓库执行 `pnpm build`，再删除你项目中的 `node_modules/.vite` 并重启开发服务器。
 
 ### 发布
 
@@ -194,7 +194,7 @@ export default defineConfig({
 | `@simple-mail/core` | 引擎 + 样式 `style.css` |
 | `@simple-mail/blocks` | 内置与示例块定义 |
 
-根包 `mail-editor-pancake` 用于占位与 link，**文档与对外示例以 `@simple-mail/*` 为准**。发布前请在各子包目录执行 build，并保证 `files` 含 `dist`。
+npm 上仅发布 `@simple-mail/core` 与 `@simple-mail/blocks`。根包 `mail-editor-pancake` 仅用于 monorepo 与本地 link。发布前需在各子包执行 build，且 `package.json` 的 `files` 包含 `dist`。
 
 ---
 
@@ -222,7 +222,7 @@ const editor = new MailEditor({
 const { mjml, html } = editor.export({ withSampleVariables: true });
 ```
 
-构造后建议注入业务变量（避免只写在 `initialDoc.variables` 里后被空数组覆盖）：
+构造后请用 `setVariables` 注入业务变量列表。若只写在 `initialDoc.variables` 中，后续 `setValue` 恢复文档时可能被空数组覆盖。
 
 ```ts
 editor.setVariables([
@@ -286,7 +286,7 @@ editor.setTheme('dark');
 editor.getTheme();
 ```
 
-根节点 `data-sm-theme`；可在宿主侧覆盖 `.sm-root` CSS 变量。
+根节点带有 `data-sm-theme`。可在你的应用中通过覆盖 `.sm-root` 上的 CSS 变量调整配色。
 
 | 方式 | 说明 |
 |------|------|
@@ -310,7 +310,7 @@ editor.getTheme();
 | `hideTopbarFullscreen?` | 隐藏全屏按钮 |
 | `hideTopbarClearCanvas?` / `hideTopbarResetContent?` | 隐藏清空 / 重置 |
 | `hideTopbarDocClipboard?` | 隐藏「复制设计稿」「导入设计稿」 |
-| `hideTopbarInsertVariable?` | 隐藏顶栏「插入变量」（由宿主提供时） |
+| `hideTopbarInsertVariable?` | 隐藏顶栏「插入变量」（改由应用内其他入口插入时） |
 | `topbarCompact?` | 顶栏默认仅图标（窄屏/嵌入） |
 | `topbarLabels?` | `auto`（默认）\| `never` \| `always`；与 `topbarCompact` 配合 |
 | `topbarCompactMinWidth?` | `topbarLabels: auto` 时展示文案的最小宽度 px，默认 1200 |
@@ -369,7 +369,7 @@ interface Variable {
 
 优先级：内联编辑光标 → 聚焦的 input/textarea → 选中 Block 主文本字段 → 末尾新建 text 块。
 
-### 宿主工具函数
+### 配套工具函数
 
 ```ts
 import {
@@ -382,26 +382,26 @@ import {
 } from '@simple-mail/core';
 ```
 
-`buildBodyVariableInsert` 仍可用，新代码请用 `buildBodyVariableKeyInsert` / `buildBodyVariableElementInsert`。
+`buildBodyVariableInsert` 为兼容保留；插入正文时优先使用 `buildBodyVariableKeyInsert` 与 `buildBodyVariableElementInsert`。
 
-### 入口分工（建议）
+### 变量插入入口
 
 | 场景 | 入口 |
 |------|------|
-| 发件主题、Preheader 等 | **宿主页**插入变量 |
-| 正文 | **编辑器顶栏** `{{ }}`（`hideTopbarInsertVariable` 时可关掉） |
+| 发件主题、Preheader 等表单字段 | 应用内表单旁的插入控件 |
+| 邮件正文 | 编辑器顶栏 `{{ }}`（可通过 `hideTopbarInsertVariable` 关闭） |
 
 ---
 
 ## 动态变量节（dynamicVariant）
 
-用于「整节内容由宿主按 key 替换」的场景（如券包 `couponGroup`）。Section 设置 `attrs.dynamicVariantKey` 后，导出 HTML/MJML 时该节正文替换为 `{{key}}`；具体 HTML 由宿主写入。
+适用于「整节 HTML 由业务系统按 key 渲染」的场景。为 Section 设置 `attrs.dynamicVariantKey` 后，导出时该节正文变为 `{{key}}` 占位符，实际内容由你的服务端或前端在发送前写入。
 
-- 编辑器 UI 默认关闭；宿主设 `ui.enableDynamicVariantKey: true` 后，右栏可编辑 key，画布显示标识。
-- 左栏 `expandPaletteDrop` 可返回 `{ blocks, sectionAttrs: { dynamicVariantKey: '…' } }` 一次拖入动态节。
-- 已写入文档的 key **不依赖** UI 开关，导出仍生效。
+- 右栏编辑入口默认关闭；设置 `ui.enableDynamicVariantKey: true` 后可在界面中配置 key，画布会显示节标识。
+- 左栏组合块可通过 `expandPaletteDrop` 返回 `{ blocks, sectionAttrs: { dynamicVariantKey: '…' } }` 一次创建动态节。
+- 文档中已保存的 key 在导出时始终生效，与 UI 开关无关。
 
-宿主可从 core 导入：
+相关 API（自 `@simple-mail/core` 导出）：
 
 ```ts
 import {
@@ -415,7 +415,7 @@ import {
 } from '@simple-mail/core';
 ```
 
-`Section.attrs.meta` 为宿主扩展袋，编辑器不解释，随 `EmailDoc` 序列化。
+`Section.attrs.meta` 为任意 JSON 扩展字段，编辑器不参与渲染，仅随 `EmailDoc` 一并序列化保存。
 
 ---
 
@@ -445,7 +445,7 @@ import {
 
 ## 图片资源 `imageAssets`
 
-编辑器只存 URL；落地由宿主实现。
+编辑器仅在文档中保存图片 URL；上传、图库与存储由你的应用实现。
 
 | 字段 | 作用 |
 |------|------|
@@ -602,13 +602,13 @@ expandPaletteDrop?: (createBlock) => Block[] | { blocks: Block[]; sectionAttrs?:
 
 ---
 
-## 宿主集成注意
+## 集成说明
 
-1. 改 core 源码后 **`pnpm build`**，再刷新宿主。
-2. **Vue**：`blocks` 用 `markRaw`。
-3. **Vite link**：`optimizeDeps.exclude` 含 `@simple-mail/core`、`@simple-mail/blocks`；配置 alias 与 codemirror/mjml/sortablejs 解析。
-4. **import 路径**：统一 `@simple-mail/*`，避免长期依赖 `mail-editor-pancake/packages/...`。
-5. 宿主需安装与 core 一致的 **codemirror、mjml-browser、sortablejs**（link 时尤甚）。
+- **依赖版本**：安装 `@simple-mail/core` 时，请同时安装 `codemirror`、`mjml-browser`、`sortablejs`，版本与 core 的 `peerDependencies` / 文档示例保持一致。
+- **import 路径**：统一使用 `@simple-mail/core`、`@simple-mail/blocks`，不要使用 `mail-editor-pancake/packages/...`。
+- **Vue 3**：将 `blocks` 数组中的每个 `BlockDefinition` 用 `markRaw` 包裹后再传入，否则 `expandPaletteDrop` 等函数可能失效。
+- **Vite + 本地 link**：在 `optimizeDeps.exclude` 中加入 `@simple-mail/core`、`@simple-mail/blocks`；按需配置 alias 与上述运行时依赖的解析路径。
+- **本地开发本仓库**：修改 `packages/core` 后执行 `pnpm build`，再在引用项目中刷新；异常时清除 `.vite` 缓存后重启 dev server。
 
 ---
 
@@ -692,7 +692,7 @@ interface Block {
 | 取舍点 | 选择 | 原因 |
 |--------|------|------|
 | 画布 HTML | 轻量预览 DOM | iframe 内 Sortable 难控；真实效果靠 MJML |
-| 嵌套 | 严格四层 | 避免 GrapesJS 式邮件翻车 |
+| 嵌套 | 严格四层 | 限制结构深度，减少邮件排版与拖拽异常 |
 | 输出 | MJML 优先 | Outlook/Gmail 兼容；可预留 table 引擎 |
 | 文档级源码回写 | 只读 | MJML→doc 反推风险大 |
 | 状态 | immutable + history | 核心零 UI 框架依赖 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mail-editor-pancake",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "面向运营的轻量邮件可视化编辑器",
   "devDependencies": {