mail-editor-pancake 0.2.3 → 0.2.6

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

@@ -65,6 +65,13 @@ export declare interface BlockDefinition<P extends object = Record<string, unkno
      * 在用户提交时按 `mode` 写回 props（rich：清理后的 innerHTML；html：原始 innerHTML；plain：textContent）。
      */
     inlineEditable?: InlineEditableConfig<P>;
+    /**
+     * 左栏拖入层级：
+     *  - `section`：自带布局（如双列卡组），与布局卡片同组，只能落在 Section 之间，不能落进 Column；
+     *  - `block`：落在 Column 内（默认）。
+     * 缺省时按 `expandPaletteDrop` 结果自动判定（多列布局 / 多列分发即视为 `section`）。
+     */
+    paletteDropLevel?: 'block' | 'section';
     /**
      * 从左栏拖入时在目标列（或自动包裹的单列 Section）中一次性插入多个块，
      * 用于「组合模板」：画布内仅为通用 image/text 等，便于逐项修改。
@@ -100,6 +107,13 @@ export declare interface BlockSchemaField {
     step?: number;
     placeholder?: string;
     help?: string;
+    /**
+     * 输入即时校验：返回文案则在字段下方红字提示，返回 null 表示通过。
+     * 只提示、不阻塞保存（运营可能故意留占位链接或使用短链）。
+     * `type: 'url'` 未设置时使用内核默认规则（见 `isRenderableHref`），
+     * 拦截 `#`、`1234`、缺协议的域名等会被 Outlook 网页端清除的链接。
+     */
+    validate?: (value: string) => string | null;
     /** 为 true 时右栏显示「继承全局」开关：开=留空跟随邮件全局，关=写入当前全局值为块级固定值 */
     inheritGlobal?: boolean;
 }
@@ -396,8 +410,12 @@ export declare interface GalleryItem {
 export declare function getSectionDynamicVariantKey(section: Section): string | undefined;
 
 export declare interface GlobalStyles {
+    /**
+     * 邮件背景色：导出时写入 `<mj-body background-color>`，画布内容纸取同一值。
+     * 旧字段 `contentBackgroundColor`（内容背景）已废弃并合并到此处，
+     * 由 `createDefaultDoc` 在读入旧文档时迁移。
+     */
     backgroundColor: string;
-    contentBackgroundColor: string;
     fontFamily: string;
     fontSize: string;
     /** 全局字重：数值档 300 | 400 | 500 | 600 | 700（兼容读写 normal / bold 等别名） */
@@ -517,10 +535,26 @@ declare interface InlineEditableConfig<P extends object = Record<string, unknown
     placeholder?: string;
 }
 
+/** 右栏链接字段默认校验：空值放行（允许暂不填），填了但不可跳转则给提示 */
+export declare function invalidHrefMessage(raw: unknown, t: (key: string) => string): string | null;
+
 export declare function isDynamicVariantSection(section: Section): boolean;
 
 export declare function isMultiColumnLayout(layout: SectionLayout): layout is MultiColumnLayout;
 
+/**
+ * 邮件链接可用性判定。
+ *
+ * Outlook 网页端（outlook.com / OWA）会清洗「不可跳转」的 href：空值、`#`、
+ * 纯数字 / 相对路径（如 `1234`）、以及非标准协议（javascript:、data: 等）。
+ * 被清洗后 `<a>` 会连同内容一起消失，表现为按钮 / 图标「元素在但看不见」。
+ *
+ * 两个用途：
+ * 1. 右栏 `type: 'url'` 字段的默认校验，输入即时提示；
+ * 2. 渲染层兜底：不可跳转时不输出 href（如 MJML 会退化为 `<p>`，样式保留、仅不可点）。
+ */
+export declare function isRenderableHref(raw: unknown): boolean;
+
 /**
  * 富文本是否「完全无内容」。
  * 空格、&nbsp;、换行（<br>）均视为有效内容；仅空串或空标签壳子算空。
@@ -754,6 +788,25 @@ export declare interface OpenImageGalleryModalOptions {
     permissions?: ImageAssetPermissions;
 }
 
+/**
+ * palette 拖入语义的判定。
+ *
+ * 画布是四层模型（Section → Column → Block），左栏也分两组：
+ *  - `sections`：布局卡片，落在 Section 之间；
+ *  - `blocks`：组件卡片，落在 Column 内。
+ *
+ * 自带布局的组件（如一次生成双列 Section 的卡组）实际会新建 Section，
+ * 若仍归到 `blocks`，拖拽时会显示「可放进列内」的占位，松手却落到该 Section 之后，
+ * 与预期不符。这里统一判定，让它与布局卡片同组，拖拽表现与布局一致。
+ */
+/** 拖入结果是否自带 Section 布局（多列布局 / 多列分发） */
+export declare function paletteDropHasSectionLayout(drop: PaletteDropResult): boolean;
+
+/** 该 palette 卡片是否按「布局」处理：只能落在 Section 之间，不能落进 Column */
+export declare function paletteDropIsSectionLevel(def: BlockDefinition, registry: Registry, opts?: {
+    enableDynamicVariantKey?: boolean;
+}): boolean;
+
 /** 左栏组合拖入：可附带新建 Section 的 attrs、布局和按列分发的 Block。 */
 export declare interface PaletteDropResult {
     /** 单列组合或落入既有列时插入的 Block。 */
@@ -865,6 +918,9 @@ export declare interface ResolvedAssetPermission {
     tip: string;
 }
 
+/** 可跳转则原样返回，否则返回空串，由调用方降级为不可点元素 */
+export declare function resolveHref(raw: unknown): string;
+
 /** 锁定块在画布上的渲染结果：preview 为 WYSIWYG HTML，source 为无法解析时的源码回退。 */
 export declare function resolveLockedMjmlCanvasContent(lockedMjml: string, padding: BlockPaddingBox): {
     mode: 'preview';
@@ -874,6 +930,9 @@ export declare function resolveLockedMjmlCanvasContent(lockedMjml: string, paddi
     source: string;
 };
 
+/** 解析 palette 拖入结果：未声明 `expandPaletteDrop` 时按单块处理 */
+export declare function resolvePaletteDropResult(def: BlockDefinition, registry: Registry): PaletteDropResult;
+
 export declare interface Section {
     id: string;
     type: 'section';