react-email-studio 3.3.1 → 3.8.0

package/CHANGELOG.md

@@ -5,12 +5,90 @@ 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.0] - 2026-05-15
+
+### Changed
+
+- **Export shape (restored)**: `exportJson` / `designToEmailDocument` again emit **`rows[]`** with **`columns[].blocks[]`** — the LMS / studio interchange format. Each row includes **`styles`**, block **`props`**, and **`_reactEmailStudio.row`** (preset, ratios, column props).
+- **Settings export**: writes **`settings._reactEmailStudio`** (`contentPadding`, `contentBorderRadius`, `editorSettings` snapshot) plus top-level **`contentPadding`** / **`contentBorderRadius`**.
+- **New blocks from palette**: content blocks are added as **new root sections** (one row each), not dropped into the first layout column.
+
+### Added
+
+- **`loadJson(design, { mode: 'replace' | 'append' })`** — append merges imported rows/blocks onto the canvas.
+- **`canonicalizeEmailDocument(input)`** — normalize any supported input to export-shaped `email_document` JSON.
+- **Section reorder**: left **⋮⋮** drag handle, larger row drop zones, and **Move section up/down** in the row inspector.
+
+### Fixed
+
+- **Root section order**: row drag-and-drop and move actions update canvas order (and exported `rows[]` order).
+- **Rich HTML**: text color in the toolbar; bullet/numbered lists in canvas, preview, and exported HTML (`email-rich-html-content` styles).
+
+### Notes for integrators
+
+- **Import**: still accepts **`blocks[]`**, legacy **`rows[]`**, **`styles`**, and **`_reactEmailStudio`**.
+- If you briefly integrated against **3.7.0** `blocks[]`-only export, use **`rows[]`** + **`_reactEmailStudio`** again — that is the primary export in **3.8.0**.
+
+## [3.7.0] - 2026-05-15
+
+### Changed
+
+- **Export shape**: `exportJson` / `designToEmailDocument` emit a flat root **`blocks[]`** instead of **`rows[]`**. Each canvas row becomes a root **`layout`** block; a row with a single content block exports that block directly at the root.
+- **Settings**: **`contentPadding`** and **`contentBorderRadius`** are top-level `settings` fields. **`_reactEmailStudio` is no longer written** on export (including `settings._reactEmailStudio` and `editorSettings` snapshots).
+- **`loadJson`**: optional second argument `{ mode: 'replace' | 'append' }` — append merges blocks/rows onto the canvas. Accepts `{ "blocks": [...] }` fragments and raw block arrays.
+
+### Notes for integrators
+
+- **Import**: legacy JSON with **`rows[]`**, **`styles`**, and **`_reactEmailStudio`** still loads.
+- **Breaking**: consumers reading **`rows`** or **`_reactEmailStudio`** from export must switch to **`blocks`** and top-level **`settings`**.
+
+## [3.6.0] - 2026-05-15
+
+### Changed
+
+- **Column layout**: per-column surface styling uses **`columns: [{ props }]`** instead of **`columnStyles`** maps (rows, nested layouts, and `email_document` columns). Legacy `columnStyles` / column `styles` still import via `columnProps` helpers.
+
+### Notes for integrators
+
+- **Row export**: **`exportJson` / `designToEmailDocument`** no longer write **`_reactEmailStudio.row`** on each row. Row shell uses **`props`** (editor field names: `bgColor`, `padding`, …), not **`styles`**. Column surfaces use **`columns[].props`**. Optional **`layout.preset`** / **`layout.ratios`**. Legacy **`styles`** / **`_reactEmailStudio.row`** still import.
+
+## [3.5.0] - 2026-05-15
+
+### Added
+
+- **`htmlToJson(html, pretty?)`**: convert an HTML fragment or full page document into an `email_document` JSON string (one row, one column, single **html** block) — suitable for `loadJson` or storage.
+- **`htmlToEmailDesignTemplate(html)`** and **`extractHtmlForDesign(html)`**: object and extraction helpers used by `htmlToJson`.
+- **`ReactEmailEditor.htmlToJson`**: static method on the component (same implementation as the standalone export).
+
+### Changed
+
+- **Rich HTML blocks (`type: "html"`)**: body markup lives on the block root as a **string** `content` field; typography and chrome stay in **`props`** (not `props.content` in exported JSON).
+- **`exportJson` / `designToEmailDocument`**: styling is carried in **`props`** only (blocks, rows, columns) — no **`styles`** on export. Legacy **`styles`** still import.
+- **`BlockBase.content`**: typed as `Record<string, unknown> | string` so `html` blocks can use a plain string at the root.
+
+### Notes for integrators
+
+- **Export shape (blocks)**: `{ id, type, content?, props }` — no block `styles`. Example **html** block: `"content": "<p>…</p>"` plus `props` for `fontSize`, `padding`, backgrounds, etc.
+- **Import**: legacy JSON with block `content` objects and/or `styles` still loads; `props` wins when present.
+- **HTML → editor**: `loadJson(htmlToJson(paste))` or `loadJson(htmlToEmailDesignTemplate(paste))`.
+- **HTML ← editor**: `jsonToHtml(exportJson)` unchanged.
+
+## [3.4.0] - 2026-05-08
+
+### Added
+
+- **`ReactEmailEditor.jsonToHtml(json, opts?)`**: static method on the component for converting a saved design (object or JSON string) to a full HTML email document — same implementation as the standalone `jsonToHtml` export, no extra setup needed.
+
+### Changed
+
+- **Empty cell drop affordance**: the "Drop here" strip is now a fixed **45px** tall row (top-level + nested columns) instead of a tall column, making compact layouts easier to scan and drop into.
+
 ## [3.1.1] - 2026-04-30
 
 ### Added
 
 - **Loading state for `loadJson`**: `ReactEmailEditor` shows a full-workspace overlay (spinner + localized “Loading design…”) while a design JSON is applied, including invalid-parse early exit.
-- **Lossless studio JSON**: document `settings._reactEmailStudio.editorSettings` stores a snapshot of editor settings; each row may include `_reactEmailStudio.row` (row fields without `cells`) for presets, ratios, `columnStyles`, etc.
+- **Lossless studio JSON**: document `settings._reactEmailStudio.editorSettings` stores a snapshot of editor settings. Row layout metadata is carried on **`layout`** (`preset`, `ratios`, …); legacy imports may still supply **`_reactEmailStudio.row`**.
 - **i18n**: `loadingDesign` string in `en`, `fr`, `de`, `es`.
 
 ### Fixed
@@ -23,5 +101,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Notes for integrators
 
-- Prefer **`loadJson` / `exportJson`** (or `designToEmailDocument` + `normalizeEmailDesignInput`) for full fidelity; blocks may include a `props` object alongside `content` / `styles` for editor-only fields.
+- Prefer **`loadJson` / `exportJson`** (or `designToEmailDocument` + `normalizeEmailDesignInput`) for full fidelity. As of **3.5.0**, exported blocks use **`props`** for styling (block `styles` are not written on export); **`html`** blocks use a root-level string **`content`**.
 - **`jsonToHtml`** nested layouts already receive `columnStyles` when present on hydrated blocks.

package/README.md

@@ -7,6 +7,8 @@
 
 ## 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.
+
 Version history and migration hints: **[CHANGELOG.md](./CHANGELOG.md)** (also included in the published npm tarball under `node_modules/react-email-studio/CHANGELOG.md`).
 
 ---
@@ -49,6 +51,7 @@ import {
   ReactEmailEditor,
   type ReactEmailEditorRef,
   jsonToHtml,
+  htmlToJson,
 } from "react-email-studio";
 
 export function App() {
@@ -88,6 +91,10 @@ export function App() {
 const html = jsonToHtml(savedDesignJson, {
   customCSS: `/* optional extra styles */`,
 });
+
+// Import existing HTML into the editor (fragment or full document)
+const designJson = htmlToJson("<p>Hello from HTML</p>", true);
+editorRef.current?.loadJson(designJson);
 ```
 
 Implement **`onUpload`** so image/video uploads return URLs your recipients can load (HTTPS recommended).
@@ -102,6 +109,11 @@ Implement **`onUpload`** so image/video uploads return URLs your recipients can
 | `ReactEmailEditorProps` | Component props type. |
 | `ReactEmailEditorRef` | Imperative API: `loadJson`, `exportJson`. |
 | `jsonToHtml` | `(design, opts?) => string` — full HTML email document. |
+| `htmlToJson` | `(html, pretty?) => string` — HTML fragment/page → `email_document` JSON. |
+| `htmlToEmailDesignTemplate` | `(html) => EmailDocument \| null` — same conversion as object. |
+| `canonicalizeEmailDocument` | `(input) => EmailDocument \| null` — normalize import/export JSON. |
+| `extractHtmlForDesign` | `(html) => string` — pull body/fragment from a full HTML document. |
+| `ReactEmailEditor.jsonToHtml` / `.htmlToJson` | Static helpers on the component. |
 | `utf8ToBase64`, `base64ToUtf8` | Encoding helpers. |
 | `EmailPreviewModal` | Standalone responsive preview modal. |
 | `emailPreviewDevices` | Device presets for preview. |

package/TUTORIAL.md

@@ -11,6 +11,7 @@ This document is for **npm users**: wiring **react-email-studio** into an app, p
 | **`ReactEmailEditor`** | Full-screen (or sized) visual editor: rows, columns, blocks, settings. |
 | **Design JSON** | Canonical storage format: `email_document` schema (see exported types). |
 | **`jsonToHtml`** | Turns saved JSON into a **full HTML document** for preview iframes or your ESP. |
+| **`htmlToJson`** | Wraps pasted HTML in `email_document` JSON for **`loadJson`**. |
 | **`onUpload`** | Your code uploads assets and returns **HTTPS URLs** referenced in the HTML. |
 
 The package does **not** send mail, host files, or provide a backend—you connect those.
@@ -188,6 +189,34 @@ Use the returned string as the **email body HTML** with your provider (SendGrid,
 
 ---
 
+## 7b. `htmlToJson` — HTML into the editor
+
+```ts
+import {
+  htmlToJson,
+  htmlToEmailDesignTemplate,
+  extractHtmlForDesign,
+} from "react-email-studio";
+
+const json = htmlToJson("<p>Welcome</p>", true); // pretty-print optional
+editorRef.current?.loadJson(json);
+
+// Or as an object:
+const doc = htmlToEmailDesignTemplate(fullPageHtml);
+if (doc) editorRef.current?.loadJson(doc);
+```
+
+| Export | Description |
+|--------|-------------|
+| `htmlToJson(html, pretty?)` | `email_document` JSON string; `""` if HTML is empty after normalization. |
+| `htmlToEmailDesignTemplate(html)` | Same design as an `EmailDocument` object, or `null`. |
+| `extractHtmlForDesign(html)` | Body/fragment only (strips `<html>` wrapper when present). |
+| `ReactEmailEditor.htmlToJson` | Static method — same as `htmlToJson`. |
+
+Creates one row, one column, and a single **html** block with default typography `props`.
+
+---
+
 ## 8. Optional: `EmailPreviewModal` & `emailPreviewDevices`
 
 For a **standalone** responsive preview (outside the built-in toolbar preview), the package exports:
@@ -239,8 +268,33 @@ import type {
 Persist **`exportJson`** output as your source of truth. Top-level shape:
 
 - `type: "email_document"`
-- `settings` — global email / content shell options
-- `rows` — layout rows → columns → blocks
+- `settings` — global shell (`width`, `backgroundColor`, `contentBackgroundColor`, `contentPadding`, `contentBorderRadius`, `fontFamily`, `rtl`, …) plus **`settings._reactEmailStudio`** (`editorSettings` snapshot).
+- `rows` — **primary export**: each canvas section is a **`type: "row"`** with `layout`, `styles`, `columns[].blocks[]`, and **`_reactEmailStudio.row`** (preset, ratios, column props).
+
+**Import** also accepts **`blocks[]`**, legacy **`styles`**, and partial fragments.
+
+### Row / block fields (export, 3.8+)
+
+| Level | Fields |
+|-------|--------|
+| Row | `id`, `type: "row"`, `layout`, `styles`, `props`, `columns`, `_reactEmailStudio.row` |
+| Column | `id`, `layout`, `styles`, `props`, `blocks[]` |
+| Block | `id`, `type`, `content`, `styles`, `props`, optional `behavior` |
+
+Blocks use **`props`** for editor fields; **`styles`** mirror the document schema for ESP compatibility. Rich **`html`** blocks use `content.html` (and `props.content`).
+
+### Optional `blocks[]` (import)
+
+A flat **`blocks[]`** root (layout or content blocks) still loads; the editor wraps standalone blocks in rows. **Export** uses **`rows[]`**, not `blocks[]`.
+
+### `loadJson` append
+
+```ts
+editorRef.current?.loadJson({ rows: [/* … */] }, { mode: "append" });
+// or { blocks: […] } / a raw array — coerced before merge
+```
+
+Use **`canonicalizeEmailDocument(input)`** to normalize saved JSON to the export shape without opening the editor.
 
 Use exported **`EmailDocument`** when typing API payloads or DB columns.
 

package/USER_README.md

@@ -17,6 +17,23 @@ For **step-by-step integration** (Next.js, APIs, TypeScript), see **`TUTORIAL.md
 - **`ref.loadJson` / `ref.exportJson`** — load or save design JSON.
 - **`onUpload`** — return a public **HTTPS** URL for uploaded images.
 - **`jsonToHtml`** — design JSON → full HTML for sending.
+- **`htmlToJson`** — paste HTML (fragment or page) → `email_document` JSON for `loadJson`.
+
+### Block JSON (3.5+)
+
+Exported blocks use **`props`** for styling (no block-level **`styles`**). Rich **html** blocks store markup as a root-level **`content`** string; other block types keep structured `content` objects where applicable.
+
+### Column layout (3.6+)
+
+Per-column backgrounds, padding, and radius use **`columns: [{ props }]`** on rows and nested layouts (not **`columnStyles`**). Legacy maps still import.
+
+### Export shape (3.8+)
+
+**`exportJson`** writes **`rows[]`** (each section = `type: "row"` with `columns[].blocks[]`), plus **`settings._reactEmailStudio`** and per-row **`_reactEmailStudio.row`** for editor round-trip. **`blocks[]`** is still accepted on **import** only.
+
+**Reorder sections**: drag the **⋮⋮** handle on the left of a row, or select the row and use **Move section up/down** in the right panel.
+
+**Append designs**: `loadJson(fragment, { mode: "append" })`.
 
 ## Troubleshooting