mail-editor-pancake 0.2.2 → 0.2.3

package/packages/core/src/editor/Canvas.ts

@@ -849,6 +849,35 @@ export class Canvas {
     return Object.keys(rest).length ? rest : undefined;
   }
 
+  /** 组合 palette 可一次创建原生多列 Section，并将 Block 放入指定列。 */
+  private _createSectionFromPaletteDrop(drop: PaletteDropResult): Section {
+    const section = createSection(drop.sectionLayout ?? '1');
+    this._applySectionAttrs(section, this._paletteSectionAttrsForDrop(drop.sectionAttrs));
+    if (drop.columnBlocks?.length) {
+      drop.columnBlocks.forEach((blocks, columnIndex) => {
+        section.columns[columnIndex]?.blocks.push(...blocks);
+      });
+    } else {
+      section.columns[0]?.blocks.push(...drop.blocks);
+    }
+    return section;
+  }
+
+  private _paletteDropNeedsDedicatedSection(drop: PaletteDropResult): boolean {
+    if (drop.sectionLayout && drop.sectionLayout !== '1') return true;
+    if ((drop.columnBlocks?.length ?? 0) > 1) return true;
+    const attrs = this._paletteSectionAttrsForDrop(drop.sectionAttrs);
+    return !!attrs?.dynamicVariantKey;
+  }
+
+  private _firstBlockInSection(section: Section): { block: Block; columnIndex: number } | undefined {
+    for (let columnIndex = 0; columnIndex < section.columns.length; columnIndex += 1) {
+      const block = section.columns[columnIndex]?.blocks[0];
+      if (block) return { block, columnIndex };
+    }
+    return undefined;
+  }
+
   private _handleSectionAdd(e: Sortable.SortableEvent) {
     this._commitEditingBeforeStructureChange();
     const item = e.item;
@@ -870,20 +899,18 @@ export class Canvas {
     // 路径 B：左栏内容/自定义卡片拖到 sections 之间 → 自动裹一列 Section
     if (sourceGroup === 'blocks' && blockType) {
       item.parentElement?.removeChild(item);
-      const { blocks, sectionAttrs } = this._resolvePaletteDrop(blockType);
-      const newSection = createSection('1');
-      this._applySectionAttrs(newSection, this._paletteSectionAttrsForDrop(sectionAttrs));
-      newSection.columns[0].blocks.splice(newIndex, 0, ...blocks);
+      const drop = this._resolvePaletteDrop(blockType);
+      const newSection = this._createSectionFromPaletteDrop(drop);
       this.opts.store.update((d) => {
         d.sections.splice(newIndex, 0, newSection);
       });
-      const head = blocks[0];
+      const head = this._firstBlockInSection(newSection);
       if (head) {
         this.opts.store.setSelection({
           kind: 'block',
           sectionId: newSection.id,
-          columnIndex: 0,
-          blockId: head.id,
+          columnIndex: head.columnIndex,
+          blockId: head.block.id,
         });
       }
       return;
@@ -938,23 +965,20 @@ export class Canvas {
     if (sourceGroup === 'blocks' && blockType) {
       item.parentElement?.removeChild(item);
       const drop = this._resolvePaletteDrop(blockType);
-      const paletteSectionAttrs = this._paletteSectionAttrsForDrop(drop.sectionAttrs);
-      if (paletteSectionAttrs?.dynamicVariantKey) {
-        const newSection = createSection('1');
-        this._applySectionAttrs(newSection, paletteSectionAttrs);
-        newSection.columns[0].blocks.push(...drop.blocks);
+      if (this._paletteDropNeedsDedicatedSection(drop)) {
+        const newSection = this._createSectionFromPaletteDrop(drop);
         this.opts.store.update((d) => {
           const secIdx = d.sections.findIndex((s) => s.id === sectionId);
           const insertAt = secIdx >= 0 ? secIdx + 1 : d.sections.length;
           d.sections.splice(insertAt, 0, newSection);
         });
-        const head = drop.blocks[0];
+        const head = this._firstBlockInSection(newSection);
         if (head) {
           this.opts.store.setSelection({
             kind: 'block',
             sectionId: newSection.id,
-            columnIndex: 0,
-            blockId: head.id,
+            columnIndex: head.columnIndex,
+            blockId: head.block.id,
           });
         }
         return;

package/packages/core/src/editor/RightPanel.ts

@@ -562,6 +562,24 @@ export class RightPanel {
             `section:${section.id}:attrs.columnGap`,
           )
         : null,
+      section.layout !== '1' && !a.preserveColumnsOnMobile
+        ? this._numberField(
+            this.opts.t('rightPanel.section.stackedGap'),
+            a.columnStackedGap ?? 0,
+            0,
+            64,
+            (v) => {
+              const g = Math.max(0, Math.min(64, Math.round(v)));
+              this.opts.store.update((d) => {
+                const s = findSection(d, section.id);
+                if (s) s.attrs.columnStackedGap = g > 0 ? g : undefined;
+              });
+            },
+            1,
+            `section:${section.id}:attrs.stackedGap`,
+            this.opts.t('rightPanel.section.stackedGapHelp'),
+          )
+        : null,
       section.layout !== '1'
         ? this._switchField(
             this.opts.t('rightPanel.section.preserveMobile'),
@@ -1137,6 +1155,24 @@ export class RightPanel {
     onChange: (v: number) => void,
     step = 1,
     focusToken?: string,
+    help?: string,
+  ): HTMLElement {
+    const field = this._buildNumberField(label, value, min, max, onChange, step, focusToken);
+    if (!help) return field;
+    return h('div', { class: 'sm-field', style: 'flex-direction:column;align-items:flex-start;gap:6px;' }, [
+      field,
+      h('div', { class: 'sm-field__help' }, [help]),
+    ]);
+  }
+
+  private _buildNumberField(
+    label: string,
+    value: number,
+    min: number,
+    max: number,
+    onChange: (v: number) => void,
+    step = 1,
+    focusToken?: string,
   ) {
     const snap = (n: number) => {
       const c = Math.min(max, Math.max(min, n));

package/packages/core/src/i18n/index.ts

@@ -140,6 +140,8 @@ export const zhCNMessages: SimpleMailMessages = {
   'rightPanel.section.widthHelp': '留空=与邮件同宽；自适应等价于清空宽度',
   'rightPanel.section.padding': '内边距',
   'rightPanel.section.columnGap': '列间距 (px)',
+  'rightPanel.section.stackedGap': '堆叠纵向间距 (px)',
+  'rightPanel.section.stackedGapHelp': '小屏堆叠为单列后，相邻列之间的额外纵向间距；0 表示沿用块自身内边距。',
   'rightPanel.section.preserveMobile': '小屏仍并排显示多列（可能字很窄）',
   'rightPanel.section.preserveMobileHelp': '开启后 MJML 会生成 mj-group，移动端预览/导出与默认「小屏堆叠列」行为不同。',
   'rightPanel.section.columnLayout': '列布局',
@@ -447,6 +449,8 @@ export const enUSMessages: SimpleMailMessages = {
   'rightPanel.section.widthHelp': 'Empty = email width. Auto is equivalent to clearing the width.',
   'rightPanel.section.padding': 'Padding',
   'rightPanel.section.columnGap': 'Column gap (px)',
+  'rightPanel.section.stackedGap': 'Stacked vertical gap (px)',
+  'rightPanel.section.stackedGapHelp': 'Extra vertical space between columns once they stack on small screens. 0 keeps each block own padding.',
   'rightPanel.section.preserveMobile': 'Keep columns side by side on small screens',
   'rightPanel.section.preserveMobileHelp': 'When enabled, MJML outputs mj-group. Mobile preview/export differs from the default stacked-column behavior.',
   'rightPanel.section.columnLayout': 'Column layout',

package/packages/core/src/renderer/mjml.ts

@@ -34,6 +34,7 @@ export function docToMjml(doc: EmailDoc, registry: Registry): string {
     <mj-style>
       a { color: ${escapeAttr(attrs.linkColor)}; }
 ${sectionWidthConstraintCss(doc)}
+${columnGapMobileCss(doc)}
     </mj-style>
   </mj-head>
   <mj-body background-color="${escapeAttr(attrs.backgroundColor)}" width="${escapeAttr(docContentWidthCss(doc.meta.width))}">
@@ -55,6 +56,65 @@ function sectionWidthConstraintCss(doc: EmailDoc): string {
     .join('\n');
 }
 
+/**
+ * 列间距相关的小屏规则。
+ *
+ * 1) 水平间距（columnGap）用 mj-column 对称 padding 实现，小屏堆叠后 padding 不消失会导致
+ *    相邻列内容纵向错位（首列右缩、次列左缩），需要在堆叠时清零。
+ * 2) 堆叠纵向间距（columnStackedGap）只挂在非末列上，作为堆叠后相邻列之间的额外间距。
+ *
+ * 共同注意点：mj-column 的 padding 不落在带 css-class 的外层 div 上，编译结果是
+ * `div[class] > table > tbody > tr > td{padding:...}`，所以规则必须命中这一层 td，
+ * 用直接子代链避免波及块自身的 padding。
+ * 断点取 MJML 默认堆叠断点 480px；!important 用于覆盖行内样式。
+ * 仅对会小屏堆叠的列生效；mj-group（preserveColumnsOnMobile）不堆叠，不注入。
+ */
+const COLUMN_GAP_MOBILE_BREAKPOINT = 480;
+
+function columnGapClassName(sectionId: string): string {
+  return `${sectionMjClassName(sectionId)}-cg`;
+}
+
+function columnStackedGapClassName(sectionId: string): string {
+  return `${sectionMjClassName(sectionId)}-svg`;
+}
+
+/** 该 Section 的列是否会在小屏堆叠（未包 mj-group 的多列） */
+function stacksOnMobile(section: Section): boolean {
+  return section.columns.length > 1 && section.attrs.preserveColumnsOnMobile !== true;
+}
+
+function columnGapMobileCss(doc: EmailDoc): string {
+  const lines: string[] = [];
+
+  for (const s of doc.sections) {
+    if (!stacksOnMobile(s)) continue;
+    const gap = Math.max(0, s.attrs.columnGap ?? 0);
+    const stackedGap = Math.max(0, Math.round(s.attrs.columnStackedGap ?? 0));
+    if (gap <= 0 && stackedGap <= 0) continue;
+
+    if (gap > 0) {
+      const cls = columnGapClassName(s.id);
+      lines.push(
+        `        .${cls},`,
+        `        .${cls} > table > tbody > tr > td { padding-left: 0 !important; padding-right: 0 !important; }`,
+      );
+    }
+    if (stackedGap > 0) {
+      lines.push(
+        `        .${columnStackedGapClassName(
+          s.id,
+        )} > table > tbody > tr > td { padding-bottom: ${stackedGap}px !important; }`,
+      );
+    }
+  }
+
+  if (!lines.length) return '';
+  return `      @media only screen and (max-width:${COLUMN_GAP_MOBILE_BREAKPOINT}px) {
+${lines.join('\n')}
+      }`;
+}
+
 function sectionToMjml(section: Section, registry: Registry, ctx: RenderContext): string {
   const a = section.attrs;
   const padding = [a.paddingTop, a.paddingRight, a.paddingBottom, a.paddingLeft]
@@ -67,10 +127,27 @@ function sectionToMjml(section: Section, registry: Registry, ctx: RenderContext)
     secW || dvKey ? ` css-class="${escapeAttr(sectionMjClassName(section.id))}"` : '';
   const widths = layoutWidths(section.layout);
   const gapPx = Math.max(0, section.attrs.columnGap ?? 0);
+  /** 仅小屏堆叠时才有水平复位与纵向间距；与下方 grouped 判定保持一致 */
+  const stacked = stacksOnMobile(section);
+  const hCls = stacked && gapPx > 0 ? columnGapClassName(section.id) : '';
+  const vCls =
+    stacked && Math.max(0, Math.round(section.attrs.columnStackedGap ?? 0)) > 0
+      ? columnStackedGapClassName(section.id)
+      : '';
+  const lastIndex = section.columns.length - 1;
 
   const columns = section.columns
     .map((col, i) =>
-      columnToMjml(col, widths[i], i, section.columns.length, gapPx, registry, ctx),
+      columnToMjml(
+        col,
+        widths[i],
+        i,
+        section.columns.length,
+        gapPx,
+        [hCls, vCls && i < lastIndex ? vCls : ''].filter(Boolean).join(' '),
+        registry,
+        ctx,
+      ),
     )
     .join('\n');
 
@@ -92,6 +169,7 @@ function columnToMjml(
   columnIndex: number,
   columnCount: number,
   columnGapPx: number,
+  gapClassNames: string,
   registry: Registry,
   ctx: RenderContext,
 ): string {
@@ -106,6 +184,7 @@ function columnToMjml(
     const pr = columnIndex < columnCount - 1 ? `${half}px` : '0px';
     gapPad = ` padding="0px ${pr} 0px ${pl}"`;
   }
+  const clsAttr = gapClassNames ? ` css-class="${escapeAttr(gapClassNames)}"` : '';
 
   const rawTypo = mjRawCellTypographyFromStyles(ctx.doc.styles);
   const blocks = column.blocks
@@ -129,7 +208,7 @@ function columnToMjml(
     })
     .join('\n');
 
-  return `      <mj-column width="${width}"${va}${bg}${gapPad}>
+  return `      <mj-column width="${width}"${va}${bg}${gapPad}${clsAttr}>
 ${blocks || '        <!-- empty column -->'}
       </mj-column>`;
 }

package/packages/core/src/types.ts

@@ -77,6 +77,13 @@ export interface SectionAttrs {
    * MJML 通过相邻 `mj-column` 对称内边距实现；画布用 flex `gap` 对齐观感。
    */
   columnGap?: number;
+  /**
+   * 多列在小屏堆叠为单列后，相邻列之间的纵向间距（px）。
+   * 仅在多列且未开启 `preserveColumnsOnMobile` 时生效；未设置/0 表示不额外加间距
+   * （沿用块自身 padding 形成的间距），避免改变已有邮件的移动端排版。
+   * 通过小屏媒体查询实现，不会影响桌面端行高。
+   */
+  columnStackedGap?: number;
   /**
    * 本节内容区最大宽度（窄于邮件 `meta.width` 时居中）。支持 `480`、`480px`、`90%`；留空则与邮件同宽。
    */
@@ -195,10 +202,21 @@ export interface BlockDefinition<P extends object = Record<string, unknown>> {
   ) => Block[] | PaletteDropResult;
 }
 
-/** 左栏组合拖入：可附带新建 Section 的 attrs（如 meta 扩展袋） */
+/** 左栏组合拖入：可附带新建 Section 的 attrs、布局和按列分发的 Block。 */
 export interface PaletteDropResult {
+  /** 单列组合或落入既有列时插入的 Block。 */
   blocks: Block[];
   sectionAttrs?: Partial<SectionAttrs>;
+  /**
+   * 组合入口可声明要新建的 Section 布局；多列布局会始终创建独立 Section，
+   * 不会被插入到用户当前选中的单列中。
+   */
+  sectionLayout?: SectionLayout;
+  /**
+   * 仅创建新 Section 时使用；每个数组对应一个 Column，索引与 Section 列顺序一致。
+   * 超出布局列数的数组会被忽略，缺少的列保持为空。
+   */
+  columnBlocks?: Block[][];
 }
 
 export interface InlineEditableConfig<P extends object = Record<string, unknown>> {