mail-editor-pancake 0.0.9 → 0.1.0

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

@@ -1,3 +1,14 @@
+/**
+ * 编译后为带 `dynamicVariantKey` 的 Section 根节点写入 `data-dv="{key}"`，供宿主 DOM 抽取。
+ */
+export declare function annotateDynamicVariantHtmlAttributes(html: string, doc: EmailDoc): string;
+
+/**
+ * 向富文本 HTML 末尾「行内」追加内容，避免落在 `</p>` 外产生换行。
+ * 无块级标签时包一层 `<p style="margin:0;">`。
+ */
+export declare function appendInlineToRichHtml(html: string, insert: string): string;
+
 /**
  * Block 是注册表驱动的：所有内置/自定义组件都遵循同一个数据形状。
  * 渲染、属性面板、代码模式三方都从注册表读取该 type 的定义。
@@ -22,8 +33,10 @@ export declare interface BlockDefinition<P extends object = Record<string, unkno
     type: string;
     /** 显示名（左栏） */
     name: string;
-    /** 分类，用于左栏分组 */
+    /** 分类，用于左栏分组与定制块角标 */
     category: 'content' | 'custom';
+    /** 左栏卡片悬停提示；未设时 custom 类块使用 UI 默认后缀 */
+    paletteTooltip?: string;
     /** 16x16 SVG 字符串 */
     icon: string;
     /** 默认 props（拖入时使用） */
@@ -49,7 +62,14 @@ export declare interface BlockDefinition<P extends object = Record<string, unkno
      * 用于「组合模板」：画布内仅为通用 image/text 等，便于逐项修改。
      * 文档里不会出现本定义的 `type`，仅作左栏入口；若需提供请返回内置块的实例。
      */
-    expandPaletteDrop?: (createBlock: (type: string) => Block) => Block[];
+    expandPaletteDrop?: (createBlock: (type: string) => Block) => Block[] | PaletteDropResult;
+}
+
+declare interface BlockPaddingBox {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
 }
 
 export declare interface BlockSchemaField {
@@ -111,17 +131,28 @@ declare interface ColumnAttrs {
 
 export declare function createSection(layout: SectionLayout): Section;
 
-/** 无后端 sample 时按 kind / label 生成预览用示例值（仅预览弹窗等场景） */
+/** 无显式 sample 时保留 Mustache 占位符；仅当宿主传入 sample 才用于可选的示例替换。 */
 export declare function defaultVariableSample(v: Pick<Variable, 'key' | 'label' | 'kind' | 'sample'>): string;
 
 /** 工厂函数，便于外部以函数式风格定义组件。 */
 export declare function defineBlock<P extends object>(def: BlockDefinition<P>): BlockDefinition<P>;
 
+export declare const DOC_CLIPBOARD_FORMAT_VERSION: 1;
+
+/** 剪贴板 / 文件 interchange 信封标识 */
+export declare const DOC_CLIPBOARD_KIND: "simple-mail/doc";
+
 /** 文档变更通知来源（右栏等可按来源决定是否保留焦点） */
 declare type DocChangedDetail = {
     source: 'mutate' | 'history' | 'replace';
 };
 
+export declare interface DocClipboardEnvelope {
+    kind: typeof DOC_CLIPBOARD_KIND;
+    formatVersion: typeof DOC_CLIPBOARD_FORMAT_VERSION;
+    doc: EmailDoc;
+}
+
 /**
  * 内容区 / 按钮等「布局宽度」解析：数字与无单位数字按 px；支持显式 `px` 与 `%`。
  */
@@ -136,6 +167,13 @@ export declare function docContentWidthCss(raw: unknown): string;
  */
 export declare function docToMjml(doc: EmailDoc, registry: Registry): string;
 
+/**
+ * 导出 HTML 上标记动态变量组合的宿主约定属性名（值为 `Section.attrs.dynamicVariantKey`）。
+ */
+export declare const DYNAMIC_VARIANT_HTML_ATTR = "data-dv";
+
+export declare function dynamicVariantPlaceholder(key: string): string;
+
 export declare interface EditorEvents {
     change: {
         doc: EmailDoc;
@@ -230,6 +268,45 @@ export declare interface EditorUiOptions {
     hideTopbarClearCanvas?: boolean;
     /** 为 true 时隐藏顶栏「重置内容」按钮。 */
     hideTopbarResetContent?: boolean;
+    /** 为 true 时隐藏顶栏「复制设计稿」「导入设计稿」按钮。 */
+    hideTopbarDocClipboard?: boolean;
+    /** 为 true 时隐藏顶栏「插入变量」按钮（由宿主在编辑器外提供时可用）。 */
+    hideTopbarInsertVariable?: boolean;
+    /**
+     * 为 true 时顶栏默认可切换为仅图标（文案收入 `title` / `aria-label`），适合窄屏或嵌入宿主。
+     * 默认 false；嵌入场景可在宿主侧设为 true。
+     */
+    topbarCompact?: boolean;
+    /**
+     * 顶栏按钮文案展示策略（在 `topbarCompact === true` 时生效）。
+     * - `auto`（默认）：仅图标；根节点进入浏览器全屏或宽度 ≥ `topbarCompactMinWidth` 时展示文案。
+     * - `never`：始终仅图标（含全屏与宽屏）。
+     * - `always`：始终展示图标旁文案（等同不启用紧凑顶栏）。
+     */
+    topbarLabels?: 'always' | 'never' | 'auto';
+    /**
+     * `topbarLabels: 'auto'` 时，根节点宽度不低于该值（px）则展示顶栏文案。默认 1200。
+     */
+    topbarCompactMinWidth?: number;
+    /**
+     * @deprecated 左栏已合并为单组，请用 `paletteBlockGroupTitle`。
+     * 仍兼容：仅 `content` 键会作为合并后分组标题的回退。
+     */
+    blockCategoryLabels?: Partial<Record<BlockDefinition['category'], string>>;
+    /** 左栏合并后的组件分组标题，默认「组件」。 */
+    paletteBlockGroupTitle?: string;
+    /** custom 类块无 `paletteTooltip` 时拼入 title 的说明后缀。 */
+    customPaletteTooltipSuffix?: string;
+    /**
+     * 仍注册、渲染、可被 palette 展开引用，但不显示在左栏的 block type（如组合块内部用的 divider）。
+     */
+    hiddenPaletteBlockTypes?: string[];
+    /**
+     * 为 true 时：右栏 Section 可配置「动态变量名」、画布展示动态变量节标识，
+     * 左栏拖入带 `sectionAttrs.dynamicVariantKey` 的组合块会创建动态变量 Section。
+     * 默认 false；宿主（如后管）按需开启。已写入文档的 key 仍会在导出时生效。
+     */
+    enableDynamicVariantKey?: boolean;
 }
 
 /**
@@ -256,6 +333,22 @@ export declare interface EmailMeta {
     width: number | string;
 }
 
+/**
+ * 将带 `dynamicVariantKey` 的 Section 从全文 HTML 中替换为占位符，并返回各 key 的编译 HTML。
+ * 优先使用导出 HTML 上的 `data-dv="{key}"` 标记。
+ */
+export declare function extractDynamicVariantSlots(html: string, doc: EmailDoc, registry: Registry): ExtractDynamicVariantSlotsResult;
+
+export declare interface ExtractDynamicVariantSlotsResult {
+    html: string;
+    variants: Record<string, string>;
+}
+
+/**
+ * 从锁定 MJML 片段提取可在画布内渲染的 HTML；无法识别时返回 null（回退源码视图）。
+ */
+export declare function extractPreviewHtmlFromLockedMjml(lockedMjml: string): string | null;
+
 export declare function findBlockLocation(doc: EmailDoc, blockId: string): {
     section: Section;
     columnIndex: number;
@@ -283,6 +376,9 @@ export declare interface GalleryItem {
     title?: string;
 }
 
+/** 本节导出后替换为 `{{dynamicVariantKey}}`，内容由宿主写入 dynamicVariant */
+export declare function getSectionDynamicVariantKey(section: Section): string | undefined;
+
 export declare interface GlobalStyles {
     backgroundColor: string;
     contentBackgroundColor: string;
@@ -294,8 +390,16 @@ export declare interface GlobalStyles {
     linkColor: string;
     /** 无单位倍数（如 1.25）或固定值（如 24px） */
     lineHeight: string;
+    /**
+     * 未单独设置缩进的列表使用的全局左缩进（px）。
+     * 不设时等价于内置默认 24px。
+     */
+    listIndentDefaultPx?: number;
 }
 
+/** HTML 块内容是否误含 MJML 标签（应只写 HTML，MJML 标签在 mj-raw 内不会被编译）。 */
+export declare function htmlContainsMjmlTags(html: string): boolean;
+
 export declare interface ImageAssetsHandlers {
     /**
      * 用户点击右侧「上传」并选择本地文件。宿主完成上传后返回 **绝对 HTTPS URL**。
@@ -371,6 +475,17 @@ declare interface InlineEditableConfig<P extends object = Record<string, unknown
     placeholder?: string;
 }
 
+export declare function isDynamicVariantSection(section: Section): boolean;
+
+export declare function isMultiColumnLayout(layout: SectionLayout): layout is MultiColumnLayout;
+
+/**
+ * 富文本是否「完全无内容」。
+ * 空格、&nbsp;、换行（<br>）均视为有效内容；仅空串或空标签壳子算空。
+ */
+export declare function isRichHtmlEffectivelyEmpty(html: string): boolean;
+
+/** @deprecated 使用 isMultiColumnLayout */
 export declare function isTwoColumnLayout(layout: SectionLayout): layout is TwoColumnLayout;
 
 declare type Listener = (detail?: DocChangedDetail) => void;
@@ -401,6 +516,10 @@ export declare class MailEditor {
     private sourceView;
     private toolbar;
     private body;
+    /** 浮层（变量列表、toast），避免挂到 grid 的 .sm-root 上被挤成窄条 */
+    private overlayLayer;
+    /** design 态右栏变量列表：未固定时点击外部收起 */
+    private variablePickerOutsideClick;
     private changeTimer;
     /** 显式品牌色时覆盖 CSS 变量；未设置则由 styles 按 light/dark 使用默认紫/靛 */
     private accentColorOverride;
@@ -410,16 +529,25 @@ export declare class MailEditor {
     private presetContentDoc;
     /** 宿主通过 setVariables 注入的列表；setValue 恢复文档后仍会写回，避免被 doc JSON 里的空数组覆盖 */
     private configuredVariables;
+    private importDocModal;
+    private topbarLayoutObserver;
+    private topbarLayoutRaf;
     private systemThemeMq;
     private readonly _onSystemThemeMqChange;
     private readonly _onFullscreenChange;
     /** design 态 Esc：块 → 父级 Section → 文档级面板（邮件设置或版式/全局样式，取决于 `ui.hideMailMeta`） */
     private _mailEscHandler;
     /**
-     * 文档级撤销/重做（捕获阶段）：焦点在右栏 input/CodeMirror 内时，冒泡到 root 的监听太晚，
-     * 浏览器会先处理控件内撤销；仅在 store 仍有历史时拦截并走全局 undo/redo。
+     * 文档级撤销/重做（捕获阶段）。
+     * - 画布内联 contenteditable：交给浏览器撤销文字，不走 store。
+     * - 右栏 input / CodeMirror：控件自带撤销，不走 store。
+     * - 其余区域：在 store 有历史时拦截并 undo/redo 整份文档。
      */
     private _mailUndoRedoHandler;
+    /** 内联编辑、右栏表单等应使用控件/浏览器本地撤销，而非文档 history */
+    private _shouldDeferToLocalUndoRedo;
+    private _storeUndo;
+    private _storeRedo;
     constructor(opts: EditorOptions);
     setValue(doc: EmailDoc): void;
     getValue(): EmailDoc;
@@ -428,7 +556,10 @@ export declare class MailEditor {
      * 会提交内联编辑并清空选中。
      */
     clearCanvas(): void;
-    /** 将画布恢复为构造时 `presetDoc`（或 `initialDoc`）对应的预置内容。 */
+    /**
+     * 将画布恢复为 `presetDoc` 快照（未传时等同构造时的预置合并结果）。
+     * 记入撤销栈（⌘Z 可恢复）；与 `setValue` 不同，不会清空 history。
+     */
     resetToPreset(): void;
     /** 更新「重置内容」的目标（例如宿主异步加载默认模板后）。 */
     setPresetDoc(partial: Partial<EmailDoc>): void;
@@ -461,6 +592,17 @@ export declare class MailEditor {
     export(opts?: {
         withSampleVariables?: boolean;
     }): RenderResult;
+    /**
+     * 将当前画布设计稿（EmailDoc JSON 信封）写入剪贴板，供另一实例「导入设计稿」使用。
+     */
+    copyDocDesign(): Promise<boolean>;
+    /** 打开导入设计稿对话框（从剪贴板或手动粘贴 JSON，覆盖当前画布）。 */
+    openImportDocDesign(): void;
+    /**
+     * 程序化导入设计稿（与对话框「应用」相同逻辑）。
+     * @returns 是否成功解析并应用
+     */
+    importDocDesignFromJson(raw: string): boolean;
     registerBlock<P extends object>(def: BlockDefinition<P>): void;
     setSelection(sel: Selection_2 | null): void;
     destroy(): void;
@@ -479,13 +621,33 @@ export declare class MailEditor {
     private _setMode;
     private _bindKeyboard;
     private _onChange;
-    private _showVariablePopover;
+    private _unbindVariablePickerOutsideClick;
+    private _bindVariablePickerOutsideClick;
+    private _closeVariablePicker;
+    private _toggleVariablePanel;
+    private _dismissVariablePopover;
+    /** 源码模式无右栏时仍用浮层选择变量 */
+    private _toggleVariablePopover;
     private _showToast;
     private _insertImageVariable;
+    /**
+     * 按当前选中插入块：block → 其后；section → 该 section 首列末尾；无选中 → 文档最后一节首列末尾。
+     */
+    private _insertBlockRelativeToSelection;
+    /** 链接变量：写入图片/按钮等块的 `href`（MJML 可点击），而非 alt 或右栏纯文本。 */
+    private _tryApplyLinkVariableToken;
+    private _schemaUrlPropKey;
+    private _setBlockUrlProp;
     /** 在焦点处插入文本或 HTML；失败时返回 false */
     private _insertAtFocus;
+    private _ensureImportDocModal;
+    private _applyImportedDoc;
     private _showExport;
     private _showPreview;
+    private _topbarLayoutContext;
+    private _syncTopbarLayout;
+    private _bindTopbarLayoutWatch;
+    private _unbindTopbarLayoutWatch;
     private _bindFullscreen;
     private _unbindFullscreen;
     private _toggleFullscreen;
@@ -516,9 +678,17 @@ export declare function mjRawCellTypographyFromStyles(s: GlobalStyles): MjRawCel
  */
 export declare function mjRawEmailTableWrap(paddingCss: string, cellInnerHtml: string, typo: MjRawCellTypography): string;
 
+/** 多列 Section 的列布局（左栏拖入默认 `1-1`，右栏可切换列数/比例） */
+export declare const MULTI_COLUMN_LAYOUTS: readonly ["1-1", "1-2", "2-1", "1-1-1"];
+
+export declare type MultiColumnLayout = (typeof MULTI_COLUMN_LAYOUTS)[number];
+
 /** 将任意历史写法映射到最近一档（normal→400，bold→700 等） */
 export declare function normalizeFontWeightStep(raw: string | undefined | null): FontWeightStep;
 
+/** 提交前：完全无内容时统一为 '' */
+export declare function normalizeRichHtmlForCommit(html: string): string;
+
 /** 规范化 Variable（补 kind、sample） */
 export declare function normalizeVariable(v: Variable): Variable;
 
@@ -535,6 +705,17 @@ export declare interface OpenImageGalleryModalOptions {
     onClose?: () => void;
 }
 
+/** 左栏组合拖入：可附带新建 Section 的 attrs（如 meta 扩展袋） */
+export declare interface PaletteDropResult {
+    blocks: Block[];
+    sectionAttrs?: Partial<SectionAttrs>;
+}
+
+/**
+ * 解析剪贴板或手动粘贴的 JSON。支持信封格式与裸 `EmailDoc`（version: '1'）。
+ */
+export declare function parseDocClipboard(raw: string): EmailDoc | null;
+
 /** 右栏输入解析存库：纯整数可存 number，其它存 string */
 export declare function parseMetaWidthFromUserInput(input: string): number | string;
 
@@ -552,6 +733,9 @@ export declare function pruneEmptySections(draft: EmailDoc): void;
  */
 export declare function pruneSectionIfEmpty(draft: EmailDoc, sectionId: string): void;
 
+/** 导入前重生成 section / column / block id，避免与当前文档冲突。 */
+export declare function regenerateDocIds(doc: EmailDoc): EmailDoc;
+
 /**
  * 组件注册表。所有内置/自定义组件都通过 `defineBlock` 注册进来；
  * 渲染、属性面板、左栏拖拽源、组件级代码模式四方都从这里读取。
@@ -582,7 +766,8 @@ declare interface RenderOptions {
     /** 渲染引擎，目前仅 'mjml'；'table' 预留作将来直输 table HTML。 */
     engine?: RenderEngine;
     /**
-     * 是否把 {{var}} 替换为示例值。设计态画布预览传 true，导出原始 HTML 传 false。
+     * 是否把 {{var}} 替换为变量的 sample 值。
+     * 设计态预览默认不替换，保持占位符；仅当变量显式配置了 sample 且调用方传 true 时才替换。
      */
     withSampleVariables?: boolean;
 }
@@ -595,12 +780,24 @@ declare interface RenderResult {
     }[];
 }
 
+/** 仅编译某一 Section，返回邮件 body 内 HTML 片段 */
+export declare function renderSectionBodyHtml(doc: EmailDoc, sectionId: string, registry: Registry): string;
+
 /**
  * 用 sample 值替换 `{{var.name}}` 占位符。仅做最简单的字符串替换，
  * 不做任何沙箱式表达式求值（邮件场景里下游模板引擎会再处理一次）。
  */
 export declare function replaceVariables(text: string, vars: Variable[]): string;
 
+/** 锁定块在画布上的渲染结果：preview 为 WYSIWYG HTML，source 为无法解析时的源码回退。 */
+export declare function resolveLockedMjmlCanvasContent(lockedMjml: string, padding: BlockPaddingBox): {
+    mode: 'preview';
+    html: string;
+} | {
+    mode: 'source';
+    source: string;
+};
+
 export declare interface Section {
     id: string;
     type: 'section';
@@ -629,10 +826,21 @@ export declare interface SectionAttrs {
      * 本节内容区最大宽度（窄于邮件 `meta.width` 时居中）。支持 `480`、`480px`、`90%`；留空则与邮件同宽。
      */
     width?: string | number;
+    /**
+     * 动态变量组合：设置后本节编译结果在导出时替换为 `{{dynamicVariantKey}}`；
+     * 具体存贮与业务含义由宿主处理（如券包 couponGroup）。
+     */
+    dynamicVariantKey?: string;
+    /**
+     * 宿主扩展元数据；编辑器不解释、不参与 MJML 编译，仅随 EmailDoc 序列化。
+     */
+    meta?: Record<string, unknown>;
 }
 
 export declare type SectionLayout = '1' | '1-1' | '1-2' | '2-1' | '1-1-1';
 
+export declare function sectionMjClassName(sectionId: string): string;
+
 export declare function sectionWidthInputString(raw: unknown): string;
 
 declare type Selection_2 = {
@@ -648,7 +856,9 @@ export { Selection_2 as Selection }
 
 declare type SelectionListener = () => void;
 
-/** 仅更新 layout 字段；两列间切换时列数不变，列内块按列下标保留 */
+export declare function serializeDocClipboard(doc: EmailDoc): string;
+
+/** 更新 layout；列数变化时增删列，被删列内块并入最后一列 */
 export declare function setSectionLayout(section: Section, layout: SectionLayout): void;
 
 /**
@@ -690,7 +900,7 @@ export declare class Store {
 /** 从 Mustache token 提取 key，如 `{{username}}` → `username` */
 export declare function tokenToVariableKey(token: string): string;
 
-/** 两列 Section 的列宽比例（左栏拖入默认 `1-1`，右栏可改为 `1-2` / `2-1`） */
+/** @deprecated 使用 MULTI_COLUMN_LAYOUTS */
 export declare const TWO_COLUMN_LAYOUTS: readonly ["1-1", "1-2", "2-1"];
 
 export declare type TwoColumnLayout = (typeof TWO_COLUMN_LAYOUTS)[number];