mail-editor-pancake 0.0.0 → 0.0.8

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

@@ -44,6 +44,12 @@ export declare interface BlockDefinition<P extends object = Record<string, unkno
      * 在用户提交时按 `mode` 写回 props（rich：清理后的 innerHTML；html：原始 innerHTML；plain：textContent）。
      */
     inlineEditable?: InlineEditableConfig<P>;
+    /**
+     * 从左栏拖入时在目标列（或自动包裹的单列 Section）中一次性插入多个块，
+     * 用于「组合模板」：画布内仅为通用 image/text 等，便于逐项修改。
+     * 文档里不会出现本定义的 `type`，仅作左栏入口；若需提供请返回内置块的实例。
+     */
+    expandPaletteDrop?: (createBlock: (type: string) => Block) => Block[];
 }
 
 export declare interface BlockSchemaField {
@@ -55,12 +61,19 @@ export declare interface BlockSchemaField {
         label: string;
         value: string;
     }[];
+    /**
+     * select 专用：`segmented` 为横向平铺分段按钮（适合少量互斥选项，如左/中/右对齐）。
+     * 默认 `default` 为下拉框。
+     */
+    selectVariant?: 'default' | 'segmented';
     /** number 用 */
     min?: number;
     max?: number;
     step?: number;
     placeholder?: string;
     help?: string;
+    /** 为 true 时右栏显示「继承全局」开关：开=留空跟随邮件全局，关=写入当前全局值为块级固定值 */
+    inheritGlobal?: boolean;
 }
 
 export declare interface Column {
@@ -151,6 +164,11 @@ declare interface EditorOptions {
     imageAssets?: ImageAssetsHandlers;
     /** 右栏控件形态等可选 UI 偏好。 */
     ui?: EditorUiOptions;
+    /**
+     * 顶栏「重置内容」恢复的目标文档（与 `initialDoc` 独立；编辑已保存邮件时仍应指向业务预置模板）。
+     * 未传时与构造时的 `initialDoc` 合并结果一致。
+     */
+    presetDoc?: Partial<EmailDoc>;
 }
 
 /** 编辑器 Chrome 配色：`system` 由 `prefers-color-scheme` 与 `data-sm-theme` 共同决定。邮件画布 `.sm-canvas` 默认仍为白纸以贴近成品。 */
@@ -159,16 +177,34 @@ export declare type EditorTheme = 'light' | 'dark' | 'system';
 /** MailEditor 可选 UI 行为（不改变文档模型） */
 export declare interface EditorUiOptions {
     /**
-     * 为 true 时：右栏数值、内边距（四行滑块+输入）、全局/组件字号（px 滑块）、字重（分段）、
+     * 为 true 时：右栏数值、内边距（四行滑块+输入）、全局/组件字号（px 滑块）、
      * Section/按钮/分隔线等「宽度」类文本字段（自适应 / px / % + 滑块）使用增强控件。
+     * 字重恒为五档平铺（300–700），不受此项影响。
      * 默认 false。
      */
     preferSliderControls?: boolean;
     /**
-     * 为 true 时隐藏右栏「主题 / Preheader」及顶栏「邮件设置」入口；仍保留「内容宽度」与「全局样式」。
+     * 为 true 时隐藏右栏「主题 / Preheader」；仍保留「内容宽度」与「全局样式」。
+     * 顶栏「邮件设置」默认仍会显示，用于回到文档级面板；若需一并隐藏请设 `hideTopbarMailSettings`。
      * 适合只搭建正文、发件主题由宿主系统管理的场景。
      */
     hideMailMeta?: boolean;
+    /**
+     * 为 true 时隐藏顶栏左侧「Simple Mail Editor」标题（嵌入宿主页面时常用）。
+     */
+    hideTopbarTitle?: boolean;
+    /**
+     * 为 true 时隐藏顶栏「邮件设置」按钮。
+     */
+    hideTopbarMailSettings?: boolean;
+    /**
+     * 为 true 时隐藏顶栏「全屏」图标按钮（浏览器原生全屏 API，作用于编辑器根节点）。
+     */
+    hideTopbarFullscreen?: boolean;
+    /** 为 true 时隐藏顶栏「清空画布」按钮。 */
+    hideTopbarClearCanvas?: boolean;
+    /** 为 true 时隐藏顶栏「重置内容」按钮。 */
+    hideTopbarResetContent?: boolean;
 }
 
 /**
@@ -203,6 +239,16 @@ export declare function findBlockLocation(doc: EmailDoc, blockId: string): {
 
 export declare function findSection(doc: EmailDoc, sectionId: string): Section | undefined;
 
+export declare const FONT_WEIGHT_STEP_OPTIONS: {
+    label: string;
+    value: string;
+}[];
+
+/** 全局与各组件字重：固定五档，便于右栏平铺或步进滑块 */
+export declare const FONT_WEIGHT_STEP_VALUES: readonly ["300", "400", "500", "600", "700"];
+
+export declare type FontWeightStep = (typeof FONT_WEIGHT_STEP_VALUES)[number];
+
 /** 图库列表中的一条资源 */
 export declare interface GalleryItem {
     id: string;
@@ -217,7 +263,7 @@ export declare interface GlobalStyles {
     contentBackgroundColor: string;
     fontFamily: string;
     fontSize: string;
-    /** 全局字重，如 normal / 500 / bold */
+    /** 全局字重：数值档 300 | 400 | 500 | 600 | 700（兼容读写 normal / bold 等别名） */
     fontWeight: string;
     color: string;
     linkColor: string;
@@ -300,6 +346,8 @@ declare interface InlineEditableConfig<P extends object = Record<string, unknown
     placeholder?: string;
 }
 
+export declare function isTwoColumnLayout(layout: SectionLayout): layout is TwoColumnLayout;
+
 declare type Listener = (detail?: DocChangedDetail) => void;
 
 /**
@@ -331,8 +379,13 @@ export declare class MailEditor {
     private changeTimer;
     /** 显式品牌色时覆盖 CSS 变量；未设置则由 styles 按 light/dark 使用默认紫/靛 */
     private accentColorOverride;
+    /** 顶栏开关：是否在画布上始终显示 Section / Block 轻量虚线边框 */
+    private showLayoutBorders;
+    /** 「重置内容」时恢复的文档快照（与当前画布内容无关） */
+    private presetContentDoc;
     private systemThemeMq;
     private readonly _onSystemThemeMqChange;
+    private readonly _onFullscreenChange;
     /** design 态 Esc：块 → 父级 Section → 文档级面板（邮件设置或版式/全局样式，取决于 `ui.hideMailMeta`） */
     private _mailEscHandler;
     /**
@@ -343,6 +396,15 @@ export declare class MailEditor {
     constructor(opts: EditorOptions);
     setValue(doc: EmailDoc): void;
     getValue(): EmailDoc;
+    /**
+     * 清空画布：移除所有 Section/Block，保留 meta、styles、variables。
+     * 会提交内联编辑并清空选中。
+     */
+    clearCanvas(): void;
+    /** 将画布恢复为构造时 `presetDoc`（或 `initialDoc`）对应的预置内容。 */
+    resetToPreset(): void;
+    /** 更新「重置内容」的目标（例如宿主异步加载默认模板后）。 */
+    setPresetDoc(partial: Partial<EmailDoc>): void;
     setVariables(vars: Variable[]): void;
     getVariables(): Variable[];
     /** 当前界面主题（`system` 不解析为 light/dark）。 */
@@ -374,6 +436,8 @@ export declare class MailEditor {
     private _blurRightPanelIfFocused;
     /** 提交内联编辑并清空选中，右栏回到文档级面板 */
     private _focusMailSettings;
+    private _confirmClearCanvas;
+    private _confirmResetContent;
     private _setMode;
     private _bindKeyboard;
     private _onChange;
@@ -381,6 +445,10 @@ export declare class MailEditor {
     private _insertVariable;
     private _showExport;
     private _showPreview;
+    private _bindFullscreen;
+    private _unbindFullscreen;
+    private _toggleFullscreen;
+    private _toggleLayoutBorders;
 }
 
 export declare function metaWidthInputString(raw: unknown): string;
@@ -407,6 +475,9 @@ export declare function mjRawCellTypographyFromStyles(s: GlobalStyles): MjRawCel
  */
 export declare function mjRawEmailTableWrap(paddingCss: string, cellInnerHtml: string, typo: MjRawCellTypography): string;
 
+/** 将任意历史写法映射到最近一档（normal→400，bold→700 等） */
+export declare function normalizeFontWeightStep(raw: string | undefined | null): FontWeightStep;
+
 /**
  * 打开内置图库弹层：搜索、分页、选图插入；可选「链接添加」「上传到图库」「删除」由 adapter 决定。
  */
@@ -426,12 +497,16 @@ export declare function parseMetaWidthFromUserInput(input: string): number | str
 /** Section 右栏输入；空字符串表示清除宽度 */
 export declare function parseSectionWidthFromUserInput(input: string): string | number | undefined;
 
+/** @deprecated 请改用 {@link pruneSectionIfEmpty}，避免误删多个空 Section */
+export declare function pruneEmptySections(draft: EmailDoc): void;
+
 /**
- * 从文档中移除「每一列都没有任何 Block」的 Section。
- * 在内容块被删除或拖走后调用，可与 `autoWrapSection` 搭配，避免唯一块离场后仍残留空壳；
- * 不会在用户仅点击「添加 Section」时单独触发，因此未拖入内容的空布局仍会保留在画布上。
+ * 若指定 Section 的每一列都没有 Block，则从文档中移除该 Section。
+ * 在内容块被删除或拖走后调用，可与 `autoWrapSection` 搭配，避免单列 Section 在唯一块离场后仍残留空壳；
+ * 多列 Section 始终保留，便于继续向各列拖入内容。
+ * 仅处理刚变空的 Section，不会误删用户事先添加、尚未拖入内容的空布局。
  */
-export declare function pruneEmptySections(draft: EmailDoc): void;
+export declare function pruneSectionIfEmpty(draft: EmailDoc, sectionId: string): void;
 
 /**
  * 组件注册表。所有内置/自定义组件都通过 `defineBlock` 注册进来；
@@ -529,6 +604,9 @@ export { Selection_2 as Selection }
 
 declare type SelectionListener = () => void;
 
+/** 仅更新 layout 字段；两列间切换时列数不变，列内块按列下标保留 */
+export declare function setSectionLayout(section: Section, layout: SectionLayout): void;
+
 /**
  * 极小的不可变 store + 发布订阅 + history。
  * 所有变更都通过 `update(fn)` 走结构化克隆，保证：
@@ -565,6 +643,11 @@ export declare class Store {
     private _notify;
 }
 
+/** 两列 Section 的列宽比例（左栏拖入默认 `1-1`，右栏可改为 `1-2` / `2-1`） */
+export declare const TWO_COLUMN_LAYOUTS: readonly ["1-1", "1-2", "2-1"];
+
+export declare type TwoColumnLayout = (typeof TWO_COLUMN_LAYOUTS)[number];
+
 export declare interface Variable {
     /** Mustache 风格变量名，例如 user.name */
     key: string;