mail-editor-pancake 0.0.0 → 0.0.8

package/README.md

@@ -23,6 +23,7 @@ Doc → Section → Column → Block       // 仅四层，不允许 Block 再含
 - **界面主题**：顶栏 **太阳 / 月亮 / 显示器** 图标切换浅色、深色、跟随系统（`prefers-color-scheme`）；中间邮件画布仍为白纸以贴近成品
 - **品牌色**：可选 `accentColor` / `setAccentColor`，覆盖强调色与选区色；可选顶栏拾色器
 - **仅搭正文**：`ui.hideMailMeta` 隐藏主题 / Preheader 与顶栏「邮件设置」，保留版式宽度与全局样式
+- **画布清空 / 重置**：顶栏「清空画布」「重置内容」；`presetDoc` 与 `initialDoc` 分离，编辑已保存邮件时重置仍回到业务预置模板
 - 包体可控：核心 + MJML + CodeMirror + 富文本，gzip ≈ 586KB
 
 ## 仓库结构
@@ -67,6 +68,12 @@ const editor = new MailEditor({
     variables: [{ key: 'user.name', label: '用户名', sample: '张三' }],
     sections: [],
   },
+  /**
+   * 顶栏「重置内容」恢复的目标（与 initialDoc 独立）。
+   * 编辑页打开已保存邮件时：initialDoc = 当前稿，presetDoc = 业务默认模板。
+   * 未传时与 initialDoc 合并结果一致。
+   */
+  // presetDoc: defaultTemplatePartial,
   /** 右栏控件形态等，见下文「UI 选项 ui」 */
   // ui: { preferSliderControls: true, hideMailMeta: true },
   // autoWrapSection: true（默认）— 把 Block 拖到 Section 之间空白处时
@@ -85,6 +92,36 @@ const { mjml, html } = editor.export({ withSampleVariables: true });
 
 // 整份替换文档（例如切换模板）；会先失焦右栏避免旧值残留
 // editor.setValue(nextDoc);
+
+// 清空画布（仅 sections 置空，保留 meta / styles / variables；可 ⌘Z 撤销）
+// editor.clearCanvas();
+
+// 恢复为 presetDoc（或构造时 initialDoc）快照
+// editor.resetToPreset();
+
+// 异步加载默认模板后更新重置目标
+// editor.setPresetDoc(defaultTemplatePartial);
+```
+
+### 画布清空与重置
+
+顶栏位于 **撤销 / 重做** 右侧（可用 `ui` 隐藏，见下表）：
+
+| 按钮 | 行为 |
+|------|------|
+| **清空画布** | 移除所有 Section / Block；`meta`、`styles`、`variables` 不变。操作前浏览器 `confirm` 确认；记入撤销栈（⌘Z 可恢复）。 |
+| **重置内容** | 整份替换为 **`presetDoc`** 快照（未传 `presetDoc` 时等同构造时的 `initialDoc` 合并结果）。操作前 `confirm` 确认；**不**走撤销栈（与 `setValue` 相同，会清空 history）。 |
+
+**宿主常见写法**：新建页 `initialDoc` 与 `presetDoc` 同为默认模板；编辑页 `initialDoc` 为接口返回的 `jsonContent`，`presetDoc` 仍为业务预置结构，避免「重置」把用户带回打开时的草稿。
+
+```ts
+const editor = new MailEditor({
+  container: el,
+  blocks: allBlocks,
+  initialDoc: loadedFromApi,      // 当前画布
+  presetDoc: businessDefaultTemplate, // 顶栏「重置内容」
+  onChange: (doc) => save(doc),
+});
 ```
 
 ### 界面主题
@@ -120,6 +157,11 @@ editor.getTheme();
 |------|------|
 | `preferSliderControls?: boolean` | 为 `true` 时右栏数值、内边距、全局/组件字号等使用滑块等增强控件。默认 `false`。 |
 | `hideMailMeta?: boolean` | 为 `true` 时：**不展示**右栏「主题」「Preheader」以及顶栏「邮件设置」按钮；右栏文档级面板改为 **「版式」（内容宽度）+「全局样式」**。`doc.meta.subject` / `preheader` 仍在数据模型中，导出 MJML 仍会生成 `<mj-title>`（可为空）、有值时才生成 `<mj-preview>`，适合发件主题由宿主系统单独维护的场景。 |
+| `hideTopbarTitle?: boolean` | 隐藏顶栏左侧产品标题（嵌入宿主页时常用）。 |
+| `hideTopbarMailSettings?: boolean` | 隐藏顶栏「邮件设置」按钮（与 `hideMailMeta` 叠加使用）。 |
+| `hideTopbarFullscreen?: boolean` | 隐藏顶栏全屏按钮。 |
+| `hideTopbarClearCanvas?: boolean` | 隐藏顶栏「清空画布」。 |
+| `hideTopbarResetContent?: boolean` | 隐藏顶栏「重置内容」。 |
 
 ### 图片资源 `imageAssets`
 
@@ -199,20 +241,23 @@ export function MailEditorView({ value, onChange }: {
 
 ```vue
 <script setup lang="ts">
-import { onMounted, onBeforeUnmount, ref } from 'vue';
-import { MailEditor, type EmailDoc } from '@simple-mail/core';
+import { markRaw, onMounted, onBeforeUnmount, ref } from 'vue';
+import { MailEditor, type BlockDefinition, type EmailDoc } from '@simple-mail/core';
 import '@simple-mail/core/style.css';
 import { allBlocks } from '@simple-mail/blocks';
 
-const props = defineProps<{ modelValue?: EmailDoc }>();
+const props = defineProps<{ modelValue?: EmailDoc; blocks?: BlockDefinition<any>[] }>();
 const emit = defineEmits<{ 'update:modelValue': [EmailDoc] }>();
 const el = ref<HTMLDivElement>();
 let editor: MailEditor | null = null;
 
 onMounted(() => {
+  const defs = props.blocks ?? allBlocks;
+  // expandPaletteDrop / schema 等依赖块定义上的函数；props 深度代理可能导致丢失，建议 markRaw
+  const stable = defs.map((d) => markRaw(d));
   editor = new MailEditor({
     container: el.value!,
-    blocks: allBlocks,
+    blocks: stable,
     initialDoc: props.modelValue,
     onChange: (doc) => emit('update:modelValue', doc),
   });
@@ -265,7 +310,8 @@ export const couponBlock = defineBlock<{ title: string; code: string; expiresAt:
 new MailEditor({ container, blocks: [...allBlocks, couponBlock] });
 ```
 
-`schema` 字段类型支持：`text | textarea | number | color | select | switch | image | url | spacing | socialLinkList`。其中 **`image`** 渲染为「URL 输入 +（可选）上传 +（可选）图库」，由 `MailEditor` 的 **`imageAssets`** 控制，见上文「图片资源 imageAssets」。
+`schema` 字段类型支持：`text | textarea | number | color | select | switch | image | url | spacing | socialLinkList`。其中 **`image`** 渲染为「URL 输入 +（可选）上传 +（可选）图库」，由 `MailEditor` 的 **`imageAssets`** 控制，见上文「图片资源 imageAssets」。  
+**社交组**（`social-group`）另有 **`iconBorderRadius`**（px，默认圆形）、**`iconSpacing`**（图标间距 px，对应 MJML `mj-social` 的 `inner-padding`），画布预览与导出共用同一套圆角/间距逻辑。
 所有字段会在右栏自动渲染表单，change 事件回写 `block.props`。
 
 ### 内联编辑 inlineEditable
@@ -280,6 +326,26 @@ new MailEditor({ container, blocks: [...allBlocks, couponBlock] });
 
 提交时机：失焦 / 单行 Enter / Esc 取消。富文本提交前会过一次白名单清洗（保留 `a/b/strong/i/em/u/s/span/p/div/ul/ol/li/h1-h6/br`，属性仅留 `href/target/rel/style/class`，`<font>` 自动转为 `<span style="...">`）。
 
+### 左栏组合模板 `expandPaletteDrop`（可选）
+
+用于「一次拖入、画布内仍是多个通用块」的预设（例如页脚 = 图片 + 若干文本），避免整段 raw MJML，又省去运营逐个从左侧拖组件。
+
+在 `BlockDefinition` 上可选声明：
+
+```ts
+expandPaletteDrop?: (createBlock: (type: string) => Block) => Block[];
+```
+
+- 从左栏拖入该条目时，引擎会在目标列（或拖到 Section 间隙时自动包裹的**单列 Section**）内 **`splice` 插入**回调返回的多个块；**文档 JSON 里不会出现该定义的 `type`**，仅在注册表中作为左栏卡片存在。
+- 回调内请使用传入的 `createBlock('image' | 'text' | …)`，以便 ID、`defaultProps` 与内置块一致。
+- `toMjml` / `renderPreview` 仍须在类型上满足 `BlockDefinition`；组合入口可选用占位的 `toMjml: () => ''`（正常不应出现在 `sections` 里）。
+
+**宿主集成注意**
+
+- 修改 `packages/core` 源码（含拖拽、`expandPaletteDrop` 等）后，请在 monorepo 根目录执行 **`pnpm build`** 或 **`pnpm --filter @simple-mail/core build`**，保证 npm/link 宿主的 **`dist`** 与类型声明同步。
+- **Vue**：若把 `blocks` 数组作为 **props** 传入再交给 `MailEditor`，响应式代理可能导致块定义上的**函数字段**不可靠；应对每个 `BlockDefinition` 使用 **`markRaw`**（或与之一致的「非响应式」引用）后再传入构造器。参见上文「Vue 集成」示例注释。
+- **Vite**：宿主若通过 **`link:` / workspace** 引用本仓库包，建议将 **`@simple-mail/core`、`@simple-mail/blocks`**（以及项目中实际 import 的等价路径，如指向本 monorepo 子包的 specifier）列入 **`optimizeDeps.exclude`**，避免 **依赖预构建缓存**与本地刚构建的 **`dist`** 不一致（常见现象：画布拖拽、`expandPaletteDrop` 等与当前源码不符）。仍异常时可删除宿主项目的 **`node_modules/.vite`** 后重启 dev。
+
 ## 操作手册
 
 | 操作 | 触发方式 |
@@ -293,6 +359,8 @@ new MailEditor({ container, blocks: [...allBlocks, couponBlock] });
 | 删除 | 选中后按 Delete/Backspace；或工具条 🗑 |
 | 复制 | 工具条 ⎘ 图标 |
 | 撤销 / 重做 | ⌘Z / ⌘⇧Z（顶栏按钮也行） |
+| 清空画布 | 顶栏「清空画布」；移除全部 Section/Block，保留全局样式与变量（可撤销） |
+| 重置内容 | 顶栏「重置内容」；恢复为 `presetDoc`（或构造时的 `initialDoc`） |
 | 插入变量 | 顶栏 `{{ }}`：编辑中插到光标处；否则插到聚焦输入框 |
 | 切换源码 / 设计 | 顶栏切换 |
 | 导出 HTML | 顶栏右上 |
@@ -308,7 +376,12 @@ new MailEditor({ container, blocks: [...allBlocks, couponBlock] });
 
 ## 数据模型 速览
 
-`EmailDoc` 为单一事实来源；设计 / 导出 / 宿主保存均围绕该 JSON。构造器中的 `initialDoc` 为 `Partial<EmailDoc>`，会与默认空邮件合并。**预置模板**可传入完整或部分 `sections`、`styles`、`variables` 等。运行时用 **`editor.setValue(doc)`** 可整份替换（例如切换模板），调用前会尽量失焦右栏输入，避免面板显示旧值。
+`EmailDoc` 为单一事实来源；设计 / 导出 / 宿主保存均围绕该 JSON。
+
+- **`initialDoc`**：`Partial<EmailDoc>`，与默认空邮件合并，作为**首次进入画布**的内容。
+- **`presetDoc`**：可选，与默认空邮件合并，作为顶栏 **「重置内容」** 的目标；未传时与 `initialDoc` 相同。编辑已保存邮件时应单独传入业务默认模板，勿与 `initialDoc` 混用。
+- **`editor.setValue(doc)`**：运行期整份替换（如切换模板）；会清空撤销栈；调用前会尽量失焦右栏输入。
+- **`editor.clearCanvas()`** / **`editor.resetToPreset()`** / **`editor.setPresetDoc(partial)`**：与顶栏按钮等价，供宿主程序化调用。
 
 ```ts
 interface EmailDoc {

package/package.json

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

package/packages/blocks/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { BlockDefinition } from '@simple-mail/core';
 
-/** 全部组件（内置 + 示例自定义） */
+/** 全部组件（内置 + 示例自定义）。业务相关块请在使用侧与 `allBlocks` 合并后传入 MailEditor。 */
 export declare const allBlocks: BlockDefinition<any>[];
 
 /** 内置组件（content 类）。可直接传给 MailEditor.blocks。 */
@@ -36,9 +36,16 @@ declare interface DividerProps {
     paddingBottom: number;
 }
 
-/** 业务示例的"自定义"组件。可作为参考或直接使用。 */
+export declare const escAttr: (s: string) => string;
+
+/** mj-social-element 体内文本转义（非属性） */
+export declare const escMjmlText: (s: string) => string;
+
+/** 业务示例的“自定义”组件。可作为参考或直接使用；正式业务块应由宿主应用注册。 */
 export declare const exampleCustomBlocks: BlockDefinition<any>[];
 
+export declare function flexJustifyFromAlign(align: 'left' | 'center' | 'right'): string;
+
 export declare const footerBlock: BlockDefinition<FooterProps>;
 
 declare interface FooterProps {
@@ -101,11 +108,31 @@ declare interface LogoProps {
     align: 'left' | 'center' | 'right';
 }
 
+/** 生成 mj-social-element 的 name 属性（与 MJML 内置图标对齐；未知平台退化为 web）。 */
+export declare function mjSocialElementName(network: string): string;
+
+export declare function mjSocialElementsLines(links: SocialLinkItem[], labelStyle: SocialGroupLabelStyle): string;
+
+export declare function paddingQuad(p: {
+    paddingTop: number;
+    paddingRight: number;
+    paddingBottom: number;
+    paddingLeft: number;
+}): string;
+
+/** 社交平台与 MJML mj-social-element 的 name 对齐（含常用内置名）。 */
+export declare const SOCIAL_NETWORK_OPTIONS: {
+    label: string;
+    value: string;
+}[];
+
 /** 与社交组一致，仅平台选项收窄为业务五件套 */
 declare interface SocialBizProps {
     elements: SocialLinkItem[];
     align: 'left' | 'center' | 'right';
     iconSize: number;
+    iconBorderRadius: number;
+    iconSpacing: number;
     labelFontSize: number;
     labelFontWeight: string;
     labelColor: string;
@@ -124,10 +151,21 @@ export declare const socialBlock: BlockDefinition<SocialBizProps>;
 
 export declare const socialGroupBlock: BlockDefinition<SocialGroupProps>;
 
+/** 社交组块级：所有带标签的链接共用同一套标签文字样式 */
+export declare interface SocialGroupLabelStyle {
+    labelFontSize: number;
+    labelFontWeight: string;
+    labelColor: string;
+}
+
 declare interface SocialGroupProps {
     elements: SocialLinkItem[];
     align: 'left' | 'center' | 'right';
     iconSize: number;
+    /** 图标圆角 (px)。0 为方形；≥999 或不少于图标半边时为圆形（默认 999） */
+    iconBorderRadius: number;
+    /** 图标之间的间距 (px)，对应 mj-social inner-padding */
+    iconSpacing: number;
     /** 标签文字字号（整组统一） */
     labelFontSize: number;
     labelFontWeight: string;
@@ -138,7 +176,16 @@ declare interface SocialGroupProps {
     paddingLeft: number;
 }
 
-declare interface SocialLinkItem {
+/** 画布预览用图标圆角 CSS（与 {@link socialIconBorderRadiusMjml} 语义一致） */
+export declare function socialIconBorderRadiusCss(iconSize: number, radiusPx: unknown): string;
+
+/** mj-social `border-radius`：0 直角；≥999 或 ≥图标半边 → 圆形裁切（999px） */
+export declare function socialIconBorderRadiusMjml(iconSize: number, radiusPx: unknown): string;
+
+/** mj-social `inner-padding`，控制图标之间的可视间距 */
+export declare function socialIconSpacingPx(spacing: unknown, fallback?: number): number;
+
+export declare interface SocialLinkItem {
     network: string;
     href: string;
     /** 图标旁文字，对应 mj-social-element 子内容 */
@@ -149,6 +196,11 @@ declare interface SocialLinkItem {
     backgroundColor?: string;
 }
 
+export declare function socialMeta(network: string): {
+    color: string;
+    preview: string;
+};
+
 export declare const spacerBlock: BlockDefinition<SpacerProps>;
 
 declare interface SpacerProps {