react-email-studio 3.8.1 → 3.8.3

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.3] - 2026-05-26
+
+### Fixed
+
+- **Context menu Move Up / Move Down** now works for all block types: root `blocks[]` sections (row reorder), stacked blocks in a `rows[]` column (in-column swap), nested layout columns, and single-block layout rows.
+- **Context menu clicks** no longer dismiss the menu before the action runs (`pointerdown` handling on the menu overlay).
+
+## [3.8.2] - 2026-05-22
+
+### Added
+
+- Added **`RELEASE.md`** as a single-file release tutorial and included it in the published npm package.
+
+### Fixed
+
+- **Text block newline handling** is now consistent in canvas preview and exported HTML: plain text line breaks render as `<br/>`, while HTML content remains passthrough.
+
 ## [3.8.0] - 2026-05-15
 
 ### Changed

package/README.md

@@ -7,7 +7,9 @@
 
 ## Release notes
 
-**Latest: 3.8.0** — export uses **`rows[]`** + **`_reactEmailStudio`** (LMS shape); palette blocks add as root sections; section reorder via drag handle or inspector.
+**Latest: 3.8.3** — fixes context menu **Move Up / Move Down** for root sections, stacked column blocks, and nested layout blocks.
+
+See **3.8.2** for the **`RELEASE.md`** npm tutorial and plain-text newline rendering fixes.
 
 Version history and migration hints: **[CHANGELOG.md](./CHANGELOG.md)** (also included in the published npm tarball under `node_modules/react-email-studio/CHANGELOG.md`).
 
@@ -121,7 +123,8 @@ Implement **`onUpload`** so image/video uploads return URLs your recipients can
 | `ReactEmailEditorOptions`, `JsonToHtmlOptions`, `EmailHtmlOptions` | Editor options and HTML generation options. |
 | `EmailDocument`, `EmailDocumentSettings`, … | JSON schema types for stored designs. |
 
-For framework setup (Next.js client/SSR), props tables, and troubleshooting, see **[TUTORIAL.md](./TUTORIAL.md)**.
+For a single-file release tutorial, see **[RELEASE.md](./RELEASE.md)**.
+For extended framework setup (Next.js client/SSR), props tables, and troubleshooting, see **[TUTORIAL.md](./TUTORIAL.md)**.
 
 ---
 

package/RELEASE.md

@@ -0,0 +1,137 @@
+# react-email-studio release tutorial (single file)
+
+Use this file as the one-stop guide for npm integration, save/load, HTML export, and API usage.
+
+## Install
+
+```bash
+npm install react-email-studio
+```
+
+Install peer dependencies in your app:
+
+- `react`, `react-dom`
+- `lucide-react`
+- TipTap v3:
+  - `@tiptap/react`
+  - `@tiptap/core`
+  - `@tiptap/starter-kit`
+  - `@tiptap/extension-link`
+  - `@tiptap/extension-placeholder`
+  - `@tiptap/extension-text-align`
+  - `@tiptap/extension-text-style`
+  - `@tiptap/extension-underline`
+
+## Minimal integration
+
+```tsx
+import { useRef, useCallback } from "react";
+import {
+  ReactEmailEditor,
+  type ReactEmailEditorRef,
+  jsonToHtml,
+} from "react-email-studio";
+
+export function MailStudioPage() {
+  const ref = useRef<ReactEmailEditorRef>(null);
+
+  const save = useCallback(() => {
+    ref.current?.exportJson((jsonString) => {
+      void fetch("/api/email-designs", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ design: jsonString }),
+      });
+    }, true);
+  }, []);
+
+  return (
+    <>
+      <button type="button" onClick={save}>Save design</button>
+      <ReactEmailEditor
+        ref={ref}
+        hideTemplates
+        onUpload={uploadImageAndReturnUrl}
+        onReady={(api) => {
+          // api.loadJson(savedDesignJsonOrObject);
+        }}
+      />
+    </>
+  );
+}
+
+async function uploadImageAndReturnUrl(file: File): Promise<string> {
+  const body = new FormData();
+  body.append("file", file);
+  const res = await fetch("/api/upload", { method: "POST", body });
+  const { url } = await res.json();
+  return url as string;
+}
+
+export function htmlFromStoredDesign(designJson: string): string {
+  return jsonToHtml(designJson);
+}
+```
+
+Important: `onUpload` must return public HTTPS URLs that recipients can access.
+
+## Next.js note
+
+The editor is client-side. Use:
+
+```tsx
+"use client";
+```
+
+If needed:
+
+```tsx
+import dynamic from "next/dynamic";
+const ReactEmailEditor = dynamic(
+  () => import("react-email-studio").then((m) => m.ReactEmailEditor),
+  { ssr: false },
+);
+```
+
+## Core API
+
+- `ref.loadJson(input)`:
+  - Accepts JSON string or object.
+  - Replaces editor content.
+- `ref.exportJson(cb, pretty?)`:
+  - Returns canonical `email_document` JSON.
+- `jsonToHtml(design, opts?)`:
+  - Converts design JSON to full HTML document.
+- `htmlToJson(html, pretty?)`:
+  - Converts pasted HTML to `email_document` JSON.
+
+## Exported helpers
+
+- `htmlToEmailDesignTemplate`
+- `extractHtmlForDesign`
+- `canonicalizeEmailDocument`
+- `utf8ToBase64`, `base64ToUtf8`
+- `EmailPreviewModal`, `emailPreviewDevices`
+
+## JSON storage shape
+
+Persist `exportJson` output as your source of truth:
+
+- `type: "email_document"`
+- `settings`
+- `rows[]` (preferred export shape)
+  - row `layout`, `styles`, `columns[].blocks[]`
+  - `_reactEmailStudio` metadata for editor round-trip
+
+Import supports legacy `blocks[]` and older styles, but export writes `rows[]`.
+
+## Troubleshooting
+
+- Missing module errors: install all peers with compatible versions.
+- Blank HTML from `jsonToHtml`: invalid/empty design input.
+- Broken email images: `onUpload` URL is private, local, or expired.
+- SSR errors: ensure client boundary (`"use client"` or dynamic `ssr: false`).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -864,6 +864,65 @@ function countBlocksInDesign(rows) {
   }, 0);
   return rows.reduce((sum, r) => sum + r.cells.reduce((s, c) => s + colBlocks(c), 0), 0);
 }
+function isSingleBlockInRow(row) {
+  if (!row?.cells) return false;
+  let count = 0;
+  for (const col of row.cells) {
+    if (!Array.isArray(col)) continue;
+    count += col.length;
+    if (count > 1) return false;
+  }
+  return count === 1;
+}
+function resolveBlockMovePlan(rows, rowId, cellIdx, blockIndex, inner) {
+  const rowIndex = rows.findIndex((r) => r.id === rowId);
+  const row = rowIndex >= 0 ? rows[rowIndex] : void 0;
+  if (!row) return null;
+  if (inner) {
+    const loc = toColumnLoc(rowId, cellIdx, {
+      parentBlockIdx: inner.parentBlockIdx,
+      innerCellIdx: inner.cellIdx
+    });
+    const col2 = getColumnBlocks(rows, loc);
+    const idx = inner.contentIdx;
+    return {
+      mode: "column",
+      blockIndex: idx,
+      canMoveUp: idx > 0,
+      canMoveDown: idx < col2.length - 1
+    };
+  }
+  const col = row.cells?.[cellIdx];
+  const colLen = Array.isArray(col) ? col.length : 0;
+  if (colLen > 1) {
+    return {
+      mode: "column",
+      blockIndex,
+      canMoveUp: blockIndex > 0,
+      canMoveDown: blockIndex < colLen - 1
+    };
+  }
+  if (colLen === 1 && (isRootContentRow(row) || isSingleBlockInRow(row))) {
+    return {
+      mode: "row",
+      canMoveUp: rowIndex > 0,
+      canMoveDown: rowIndex < rows.length - 1
+    };
+  }
+  if (colLen === 1) {
+    return {
+      mode: "row",
+      canMoveUp: rowIndex > 0,
+      canMoveDown: rowIndex < rows.length - 1
+    };
+  }
+  return {
+    mode: "column",
+    blockIndex,
+    canMoveUp: false,
+    canMoveDown: false
+  };
+}
 
 // src/lib/htmlUtils.ts
 function escHtmlAttr(s) {
@@ -872,6 +931,11 @@ function escHtmlAttr(s) {
 function escHtml(s) {
   return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+function textBlockContentToHtml(content) {
+  const raw = typeof content === "string" ? content : "";
+  if (/^\s*<[^>]+>/.test(raw)) return raw;
+  return escHtml(raw).replace(/\r?\n/g, "<br/>");
+}
 function utf8ToBase64(raw) {
   const bytes = new TextEncoder().encode(raw);
   let bin = "";
@@ -1212,8 +1276,7 @@ function blockToHtml(cb) {
     case "text": {
       const shell = emailSurfaceBgCss(p);
       const inner = `font-size:${lenPx(p.fontSize)};color:${p.color};text-align:${p.align};font-weight:${p.fontWeight || 400};font-style:${p.italic ? "italic" : "normal"};text-decoration:${p.underline ? "underline" : "none"};line-height:${lh(p.lineHeight)};letter-spacing:${lenPx(p.letterSpacing)};font-family:${p.fontFamily || "Georgia,serif"}`;
-      const content = typeof p.content === "string" ? p.content : "";
-      const body = /^\s*<[^>]+>/.test(content) ? content : escHtml(content).replace(/\r?\n/g, "<br/>");
+      const body = textBlockContentToHtml(p.content);
       return `<div style="${pd(p.padding)};${marginCss()}${shell}"><div style="${inner}">${body}</div></div>`;
     }
     case "html": {
@@ -3052,7 +3115,7 @@ function ContentBlock({ block, selected, onClick, preview, C }) {
       "div",
       {
         style: { fontSize: p.fontSize, color: p.color, textAlign: p.align, fontWeight: p.fontWeight || (p.bold ? 700 : 400), fontStyle: p.italic ? "italic" : "normal", textDecoration: p.underline ? "underline" : "none", lineHeight: p.lineHeight || 1.65, letterSpacing: `${p.letterSpacing || 0}px`, fontFamily: p.fontFamily || "Georgia,serif" },
-        dangerouslySetInnerHTML: { __html: p.content }
+        dangerouslySetInnerHTML: { __html: textBlockContentToHtml(p.content) }
       }
     )
   );
@@ -7424,50 +7487,64 @@ var import_jsx_runtime8 = require("react/jsx-runtime");
 function ContextMenu({ x, y, items, onClose, C }) {
   const ref = (0, import_react6.useRef)(null);
   (0, import_react6.useEffect)(() => {
-    const h = () => onClose();
-    window.addEventListener("mousedown", h);
-    window.addEventListener("keydown", h);
+    const onPointerDown = (ev) => {
+      if (ref.current?.contains(ev.target)) return;
+      onClose();
+    };
+    const onKeyDown = (ev) => {
+      if (ev.key === "Escape") onClose();
+    };
+    window.addEventListener("pointerdown", onPointerDown);
+    window.addEventListener("keydown", onKeyDown);
     return () => {
-      window.removeEventListener("mousedown", h);
-      window.removeEventListener("keydown", h);
+      window.removeEventListener("pointerdown", onPointerDown);
+      window.removeEventListener("keydown", onKeyDown);
     };
   }, [onClose]);
-  return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("div", { ref, onMouseDown: (e) => e.stopPropagation(), style: { position: "fixed", left: x, top: y, zIndex: 9999, background: C.sidebar, border: `1px solid ${C.border}`, borderRadius: 7, padding: "4px 0", boxShadow: `0 8px 32px rgba(0,0,0,.4)`, minWidth: 160 }, children: items.map((item, i) => item.sep ? /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("div", { style: { height: 1, background: C.border, margin: "3px 0" } }, i) : /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(
-    "button",
+  return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
+    "div",
     {
-      type: "button",
-      disabled: !!item.disabled,
-      onClick: () => {
-        if (item.disabled) return;
-        item.action();
-        onClose();
-      },
-      style: {
-        display: "block",
-        width: "100%",
-        background: "none",
-        border: "none",
-        padding: "7px 14px",
-        textAlign: "left",
-        cursor: item.disabled ? "not-allowed" : "pointer",
-        fontSize: 12,
-        color: item.disabled ? C.muted : item.danger ? C.danger : C.text,
-        fontWeight: item.bold ? 700 : 400,
-        opacity: item.disabled ? 0.45 : 1
-      },
-      onMouseEnter: (e) => {
-        if (!item.disabled) e.currentTarget.style.background = C.surface;
-      },
-      onMouseLeave: (e) => {
-        e.currentTarget.style.background = "none";
-      },
-      children: [
-        item.icon && /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("span", { style: { marginRight: 8 }, children: item.icon }),
-        item.label
-      ]
-    },
-    i
-  )) });
+      ref,
+      onPointerDown: (e) => e.stopPropagation(),
+      style: { position: "fixed", left: x, top: y, zIndex: 9999, background: C.sidebar, border: `1px solid ${C.border}`, borderRadius: 7, padding: "4px 0", boxShadow: `0 8px 32px rgba(0,0,0,.4)`, minWidth: 160 },
+      children: items.map((item, i) => item.sep ? /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("div", { style: { height: 1, background: C.border, margin: "3px 0" } }, i) : /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(
+        "button",
+        {
+          type: "button",
+          disabled: !!item.disabled,
+          onClick: () => {
+            if (item.disabled) return;
+            item.action();
+            onClose();
+          },
+          style: {
+            display: "block",
+            width: "100%",
+            background: "none",
+            border: "none",
+            padding: "7px 14px",
+            textAlign: "left",
+            cursor: item.disabled ? "not-allowed" : "pointer",
+            fontSize: 12,
+            color: item.disabled ? C.muted : item.danger ? C.danger : C.text,
+            fontWeight: item.bold ? 700 : 400,
+            opacity: item.disabled ? 0.45 : 1
+          },
+          onMouseEnter: (e) => {
+            if (!item.disabled) e.currentTarget.style.background = C.surface;
+          },
+          onMouseLeave: (e) => {
+            e.currentTarget.style.background = "none";
+          },
+          children: [
+            item.icon && /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("span", { style: { marginRight: 8 }, children: item.icon }),
+            item.label
+          ]
+        },
+        i
+      ))
+    }
+  );
 }
 
 // src/editor/overlays/ConfirmDialog.tsx
@@ -8071,10 +8148,27 @@ var ReactEmailEditorComponent = (0, import_react8.forwardRef)(
         else dropContent(rowId, cellIdx, { kind: "duplicate", fromIdx: contentIdx });
       }
     };
+    const shiftBlockFromMenu = (rowId, cellIdx, ci, dir, inner = null) => {
+      const blockIndex = inner ? inner.contentIdx : ci;
+      const plan = resolveBlockMovePlan(rowsRef.current, rowId, cellIdx, blockIndex, inner);
+      if (!plan) return;
+      if (dir < 0 && !plan.canMoveUp || dir > 0 && !plan.canMoveDown) return;
+      if (plan.mode === "row") {
+        moveRow(rowId, dir);
+        return;
+      }
+      moveContent(rowId, cellIdx, plan.blockIndex, dir, inner);
+    };
     const handleContextMenu = (e, rowId, cellIdx, ci, inner = null) => {
+      e.preventDefault();
+      e.stopPropagation();
+      const blockIndex = inner ? inner.contentIdx : ci;
+      const plan = resolveBlockMovePlan(rowsRef.current, rowId, cellIdx, blockIndex, inner);
+      const canMoveUp = plan?.canMoveUp ?? false;
+      const canMoveDown = plan?.canMoveDown ?? false;
       setCtxMenu({ x: e.clientX, y: e.clientY, items: [
-        { icon: "\u2191", label: "Move Up", action: () => moveContent(rowId, cellIdx, ci, -1, inner) },
-        { icon: "\u2193", label: "Move Down", action: () => moveContent(rowId, cellIdx, ci, 1, inner) },
+        { icon: "\u2191", label: "Move Up", disabled: !canMoveUp, action: () => shiftBlockFromMenu(rowId, cellIdx, ci, -1, inner) },
+        { icon: "\u2193", label: "Move Down", disabled: !canMoveDown, action: () => shiftBlockFromMenu(rowId, cellIdx, ci, 1, inner) },
         { sep: true },
         { icon: "\u29C9", label: "Duplicate", action: () => dropContent(rowId, cellIdx, inner ? { kind: "duplicate", fromIdx: inner.contentIdx, fromNested: { parentBlockIdx: inner.parentBlockIdx, innerCellIdx: inner.cellIdx } } : { kind: "duplicate", fromIdx: ci }) },
         { sep: true },
@@ -8084,17 +8178,14 @@ var ReactEmailEditorComponent = (0, import_react8.forwardRef)(
     const handleLayoutContextMenu = (e, rowId) => {
       e.preventDefault();
       e.stopPropagation();
-      const ri = rows.findIndex((r) => r.id === rowId);
+      const currentRows = rowsRef.current;
+      const ri = currentRows.findIndex((r) => r.id === rowId);
       setSelectedRowId(rowId);
       setSelContentId(null);
       setSelMeta(null);
       setCtxMenu({ x: e.clientX, y: e.clientY, items: [
-        { icon: "\u2191", label: "Move row up", disabled: ri <= 0, action: () => {
-          if (ri > 0) moveRow(rowId, -1);
-        } },
-        { icon: "\u2193", label: "Move row down", disabled: ri < 0 || ri >= rows.length - 1, action: () => {
-          if (ri >= 0 && ri < rows.length - 1) moveRow(rowId, 1);
-        } },
+        { icon: "\u2191", label: "Move row up", disabled: ri <= 0, action: () => moveRow(rowId, -1) },
+        { icon: "\u2193", label: "Move row down", disabled: ri < 0 || ri >= currentRows.length - 1, action: () => moveRow(rowId, 1) },
         { sep: true },
         { icon: "\u29C9", label: "Duplicate row", action: () => dupRow(rowId) },
         { sep: true },