react-email-studio 2.0.0 → 3.1.1

package/TUTORIAL.md

@@ -1,264 +1,264 @@
-# react-email-studio — Integration tutorial & API reference
-
-This document is for **npm users**: wiring **react-email-studio** into an app, persisting designs, generating HTML, and using optional APIs (preview modal, helpers, TypeScript types).
-
----
-
-## What you are integrating
-
-| Piece | Role |
-|--------|------|
-| **`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. |
-| **`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.
-
----
-
-## 1. Install
-
-```bash
-npm install react-email-studio
-```
-
-Install **peer dependencies** in your app (same major versions as in this package’s `peerDependencies`):
-
-- `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`
-
-TypeScript projects should also have **`@types/react`** and **`@types/react-dom`** as dev dependencies.
-
----
-
-## 2. Minimal integration (save / load)
-
-```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, _pretty) => {
-      // POST jsonString to your API or write to localStorage
-      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
-        onReady={(api) => {
-          // Load previously saved JSON (string or parsed object)
-          // const saved = await fetch(...).then(r => r.json());
-          // api.loadJson(saved.design);
-        }}
-        onUpload={uploadImageAndReturnUrl}
-        options={{ locale: "en" }}
-      />
-    </>
-  );
-}
-
-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;
-}
-
-// Server-side or after save: build HTML for sending
-function htmlFromStoredDesign(designJson: string) {
-  return jsonToHtml(designJson, {
-    customCSS: `/* optional: brand overrides */`,
-  });
-}
-```
-
-**Important:** `onUpload` must return a URL that **email recipients** can open (usually `https://…`). Avoid `localhost` or short-lived signed URLs unless you understand deliverability.
-
----
-
-## 3. Framework notes
-
-### Vite / Create React App
-
-Import the editor like any other component. No special config is required beyond installing peers.
-
-### Next.js (App Router)
-
-The editor depends on the DOM and TipTap. Use a **client** boundary:
-
-```tsx
-"use client";
-
-import { ReactEmailEditor } from "react-email-studio";
-// ...
-```
-
-If you see SSR-related errors (window/document during prerender), load the editor only on the client:
-
-```tsx
-import dynamic from "next/dynamic";
-
-const ReactEmailEditor = dynamic(
-  () => import("react-email-studio").then((m) => m.ReactEmailEditor),
-  { ssr: false },
-);
-```
-
-Adjust the import path to match your structure.
-
----
-
-## 4. `ReactEmailEditor` — props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `ref` | `ReactEmailEditorRef` | Imperative API: `loadJson`, `exportJson` (see below). |
-| `options` | `ReactEmailEditorOptions` | Editor chrome, locale, merge tags, feature flags, etc. (see §6). |
-| `onUpload` | `(file: File) => Promise<string>` | Required for good image/video UX; return public URL string. |
-| `onLoad` / `onReady` | `(api: ReactEmailEditorRef) => void` | Fired once with the same API object; use to call `loadJson` with server data. |
-| `hideTemplates` | `boolean` | Hide built-in templates UI; use when you only load via `loadJson`. |
-| `templates` | `{ name: string; design: unknown; thumbnail?: string }[]` | Optional starter templates. |
-| `minHeight` | `string` | Default `"100vh"`. |
-| `editorId` | `string` | Prefix for DOM ids (multiple editors on one page). |
-| `style` | `CSSProperties` | Outer wrapper style. |
-
----
-
-## 5. Imperative API (`ReactEmailEditorRef`)
-
-| Method | Description |
-|--------|-------------|
-| `loadJson(input: string \| Record<string, unknown>)` | Replace editor content from JSON string or object (invalid input is ignored safely). |
-| `exportJson(cb: (json: string) => void, pretty?: boolean)` | Current design as JSON string (`email_document`). Use `pretty === true` for readable storage diffs. |
-
----
-
-## 6. `options` (`ReactEmailEditorOptions`)
-
-`ReactEmailEditorOptions` extends HTML generation hints with **`customCSS`** (injected in preview HTML) plus editor behavior:
-
-| Area | Examples |
-|------|----------|
-| **`customCSS`** | Extra `<style>` content for generated HTML (preview / export parity). |
-| **`appearance`** | `theme`, `colors`, `customThemes` — chrome theming. |
-| **`locale`** | `"en"` \| `"fr"` \| `"de"` \| `"es"` for UI strings. |
-| **`mergeTags`** | `{ name: string; value: string }[]` for rich-text insertion. |
-| **`features.autoSave`** | `{ enabled?: boolean; interval?: number }` — UI autosave hint. |
-| **`tools`** | `{ [blockType: string]: { enabled?: boolean } }` — toggle blocks. |
-| **`blockLibrary`** | `groupHeadings`, `paletteGroupLabels` — library copy overrides. |
-
-Full typings ship with the package (`ReactEmailEditorOptions`).
-
----
-
-## 7. `jsonToHtml` — HTML for preview & ESP
-
-```ts
-import { jsonToHtml, type JsonToHtmlOptions } from "react-email-studio";
-
-const html: string = jsonToHtml(designInput, options);
-```
-
-| Argument | Description |
-|----------|-------------|
-| `designInput` | `unknown` — JSON string or parsed object; invalid or empty designs yield `""`. |
-| `options` | `JsonToHtmlOptions` (= `EmailHtmlOptions`): `{ customCSS?: string }`. |
-
-Use the returned string as the **email body HTML** with your provider (SendGrid, SES, Mailgun, Postmark, …). Test in real clients (Gmail, Outlook, Apple Mail).
-
----
-
-## 8. Optional: `EmailPreviewModal` & `emailPreviewDevices`
-
-For a **standalone** responsive preview (outside the built-in toolbar preview), the package exports:
-
-- **`EmailPreviewModal`** — modal with device frames.
-- **`emailPreviewDevices`** — device metadata for labels/layout.
-
-You must pass **`html`** (from `jsonToHtml` or your pipeline) and a theme map **`C`** (`Record<string, string>`) for chrome colors—mirror the palette you use in your app or define a minimal set for the modal.
-
-See TypeScript types **`EmailPreviewModalProps`** and **`MobilePreviewVariant`** (`"iphone"` \| `"android"`).
-
----
-
-## 9. Encoding helpers
-
-| Export | Purpose |
-|--------|---------|
-| `utf8ToBase64(raw: string)` | Encode UTF-8 text to Base64. |
-| `base64ToUtf8(b64: string)` | Decode Base64 to UTF-8 string. |
-
-Useful for data URLs or compact transport—not email-specific.
-
----
-
-## 10. TypeScript — exported types
-
-Import names match what you get from the package entry:
-
-| Type | Purpose |
-|------|---------|
-| `ReactEmailEditorProps`, `ReactEmailEditorRef`, `ReactEmailEditorOptions` | Component contract. |
-| `JsonToHtmlOptions`, `EmailHtmlOptions` | HTML generation options (`customCSS`). |
-| `EmailDocument`, `EmailDocumentSettings`, `EmailDocumentRow`, `EmailDocumentColumn`, `BlockBase` | JSON schema shapes for storage / validation. |
-| `EmailPreviewModalProps`, `MobilePreviewVariant` | Preview modal. |
-
-Example:
-
-```ts
-import type {
-  EmailDocument,
-  ReactEmailEditorRef,
-} from "react-email-studio";
-```
-
----
-
-## 11. JSON schema (`email_document`)
-
-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
-
-Use exported **`EmailDocument`** when typing API payloads or DB columns.
-
----
-
-## 12. Troubleshooting
-
-| Issue | What to check |
-|-------|----------------|
-| Module not found (TipTap / lucide) | Install all peer dependencies; TipTap majors must align (v3). |
-| Blank HTML from `jsonToHtml` | Empty rows after normalization, or invalid JSON. |
-| Broken images in sent mail | URLs from `onUpload` must be publicly reachable from recipient networks. |
-| SSR errors in Next.js | `"use client"` and/or `dynamic(..., { ssr: false })`. |
-
----
-
-
-## License
-
-MIT — see `package.json`.
+# react-email-studio — Integration tutorial & API reference
+
+This document is for **npm users**: wiring **react-email-studio** into an app, persisting designs, generating HTML, and using optional APIs (preview modal, helpers, TypeScript types).
+
+---
+
+## What you are integrating
+
+| Piece | Role |
+|--------|------|
+| **`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. |
+| **`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.
+
+---
+
+## 1. Install
+
+```bash
+npm install react-email-studio
+```
+
+Install **peer dependencies** in your app (same major versions as in this package’s `peerDependencies`):
+
+- `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`
+
+TypeScript projects should also have **`@types/react`** and **`@types/react-dom`** as dev dependencies.
+
+---
+
+## 2. Minimal integration (save / load)
+
+```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, _pretty) => {
+      // POST jsonString to your API or write to localStorage
+      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
+        onReady={(api) => {
+          // Load previously saved JSON (string or parsed object)
+          // const saved = await fetch(...).then(r => r.json());
+          // api.loadJson(saved.design);
+        }}
+        onUpload={uploadImageAndReturnUrl}
+        options={{ locale: "en" }}
+      />
+    </>
+  );
+}
+
+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;
+}
+
+// Server-side or after save: build HTML for sending
+function htmlFromStoredDesign(designJson: string) {
+  return jsonToHtml(designJson, {
+    customCSS: `/* optional: brand overrides */`,
+  });
+}
+```
+
+**Important:** `onUpload` must return a URL that **email recipients** can open (usually `https://…`). Avoid `localhost` or short-lived signed URLs unless you understand deliverability.
+
+---
+
+## 3. Framework notes
+
+### Vite / Create React App
+
+Import the editor like any other component. No special config is required beyond installing peers.
+
+### Next.js (App Router)
+
+The editor depends on the DOM and TipTap. Use a **client** boundary:
+
+```tsx
+"use client";
+
+import { ReactEmailEditor } from "react-email-studio";
+// ...
+```
+
+If you see SSR-related errors (window/document during prerender), load the editor only on the client:
+
+```tsx
+import dynamic from "next/dynamic";
+
+const ReactEmailEditor = dynamic(
+  () => import("react-email-studio").then((m) => m.ReactEmailEditor),
+  { ssr: false },
+);
+```
+
+Adjust the import path to match your structure.
+
+---
+
+## 4. `ReactEmailEditor` — props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `ref` | `ReactEmailEditorRef` | Imperative API: `loadJson`, `exportJson` (see below). |
+| `options` | `ReactEmailEditorOptions` | Editor chrome, locale, merge tags, feature flags, etc. (see §6). |
+| `onUpload` | `(file: File) => Promise<string>` | Required for good image/video UX; return public URL string. |
+| `onLoad` / `onReady` | `(api: ReactEmailEditorRef) => void` | Fired once with the same API object; use to call `loadJson` with server data. |
+| `hideTemplates` | `boolean` | Hide built-in templates UI; use when you only load via `loadJson`. |
+| `templates` | `{ name: string; design: unknown; thumbnail?: string }[]` | Optional starter templates. |
+| `minHeight` | `string` | Default `"100vh"`. |
+| `editorId` | `string` | Prefix for DOM ids (multiple editors on one page). |
+| `style` | `CSSProperties` | Outer wrapper style. |
+
+---
+
+## 5. Imperative API (`ReactEmailEditorRef`)
+
+| Method | Description |
+|--------|-------------|
+| `loadJson(input: string \| Record<string, unknown>)` | Replace editor content from JSON string or object (invalid input is ignored safely). |
+| `exportJson(cb: (json: string) => void, pretty?: boolean)` | Current design as JSON string (`email_document`). Use `pretty === true` for readable storage diffs. |
+
+---
+
+## 6. `options` (`ReactEmailEditorOptions`)
+
+`ReactEmailEditorOptions` extends HTML generation hints with **`customCSS`** (injected in preview HTML) plus editor behavior:
+
+| Area | Examples |
+|------|----------|
+| **`customCSS`** | Extra `<style>` content for generated HTML (preview / export parity). |
+| **`appearance`** | `theme`, `colors`, `customThemes` — chrome theming. |
+| **`locale`** | `"en"` \| `"fr"` \| `"de"` \| `"es"` for UI strings. |
+| **`mergeTags`** | `{ name: string; value: string }[]` for rich-text insertion. |
+| **`features.autoSave`** | `{ enabled?: boolean; interval?: number }` — UI autosave hint. |
+| **`tools`** | `{ [blockType: string]: { enabled?: boolean } }` — toggle blocks. |
+| **`blockLibrary`** | `groupHeadings`, `paletteGroupLabels` — library copy overrides. |
+
+Full typings ship with the package (`ReactEmailEditorOptions`).
+
+---
+
+## 7. `jsonToHtml` — HTML for preview & ESP
+
+```ts
+import { jsonToHtml, type JsonToHtmlOptions } from "react-email-studio";
+
+const html: string = jsonToHtml(designInput, options);
+```
+
+| Argument | Description |
+|----------|-------------|
+| `designInput` | `unknown` — JSON string or parsed object; invalid or empty designs yield `""`. |
+| `options` | `JsonToHtmlOptions` (= `EmailHtmlOptions`): `{ customCSS?: string }`. |
+
+Use the returned string as the **email body HTML** with your provider (SendGrid, SES, Mailgun, Postmark, …). Test in real clients (Gmail, Outlook, Apple Mail).
+
+---
+
+## 8. Optional: `EmailPreviewModal` & `emailPreviewDevices`
+
+For a **standalone** responsive preview (outside the built-in toolbar preview), the package exports:
+
+- **`EmailPreviewModal`** — modal with device frames.
+- **`emailPreviewDevices`** — device metadata for labels/layout.
+
+You must pass **`html`** (from `jsonToHtml` or your pipeline) and a theme map **`C`** (`Record<string, string>`) for chrome colors—mirror the palette you use in your app or define a minimal set for the modal.
+
+See TypeScript types **`EmailPreviewModalProps`** and **`MobilePreviewVariant`** (`"iphone"` \| `"android"`).
+
+---
+
+## 9. Encoding helpers
+
+| Export | Purpose |
+|--------|---------|
+| `utf8ToBase64(raw: string)` | Encode UTF-8 text to Base64. |
+| `base64ToUtf8(b64: string)` | Decode Base64 to UTF-8 string. |
+
+Useful for data URLs or compact transport—not email-specific.
+
+---
+
+## 10. TypeScript — exported types
+
+Import names match what you get from the package entry:
+
+| Type | Purpose |
+|------|---------|
+| `ReactEmailEditorProps`, `ReactEmailEditorRef`, `ReactEmailEditorOptions` | Component contract. |
+| `JsonToHtmlOptions`, `EmailHtmlOptions` | HTML generation options (`customCSS`). |
+| `EmailDocument`, `EmailDocumentSettings`, `EmailDocumentRow`, `EmailDocumentColumn`, `BlockBase` | JSON schema shapes for storage / validation. |
+| `EmailPreviewModalProps`, `MobilePreviewVariant` | Preview modal. |
+
+Example:
+
+```ts
+import type {
+  EmailDocument,
+  ReactEmailEditorRef,
+} from "react-email-studio";
+```
+
+---
+
+## 11. JSON schema (`email_document`)
+
+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
+
+Use exported **`EmailDocument`** when typing API payloads or DB columns.
+
+---
+
+## 12. Troubleshooting
+
+| Issue | What to check |
+|-------|----------------|
+| Module not found (TipTap / lucide) | Install all peer dependencies; TipTap majors must align (v3). |
+| Blank HTML from `jsonToHtml` | Empty rows after normalization, or invalid JSON. |
+| Broken images in sent mail | URLs from `onUpload` must be publicly reachable from recipient networks. |
+| SSR errors in Next.js | `"use client"` and/or `dynamic(..., { ssr: false })`. |
+
+---
+
+
+## License
+
+MIT — see `package.json`.

package/USER_README.md

@@ -1,28 +1,28 @@
-# react-email-studio — User guide
-
-For **install, quick start, and export list**, see **`README.md`** on npm.
-
-For **step-by-step integration** (Next.js, APIs, TypeScript), see **`TUTORIAL.md`**.
-
-## Editor areas
-
-| Area | Role |
-|------|------|
-| **Canvas** | Drag blocks, click to select rows/blocks, zoom, preview. |
-| **Right rail** | Block inspector, row settings, **Blocks** / **Settings** tabs. |
-| **Toolbar** | Undo/redo, templates (if enabled), preview. |
-
-## Core APIs
-
-- **`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.
-
-## Troubleshooting
-
-| Issue | Check |
-|-------|--------|
-| Module not found | Install all **peer** packages (React, TipTap v3, `lucide-react`). |
-| Broken images in mail | `onUpload` URLs must be reachable by recipients (not `localhost`). |
-
-MIT — see `package.json`.
+# react-email-studio — User guide
+
+For **install, quick start, and export list**, see **`README.md`** on npm.
+
+For **step-by-step integration** (Next.js, APIs, TypeScript), see **`TUTORIAL.md`**.
+
+## Editor areas
+
+| Area | Role |
+|------|------|
+| **Canvas** | Drag blocks, click to select rows/blocks, zoom, preview. |
+| **Right rail** | Block inspector, row settings, **Blocks** / **Settings** tabs. |
+| **Toolbar** | Undo/redo, templates (if enabled), preview. |
+
+## Core APIs
+
+- **`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.
+
+## Troubleshooting
+
+| Issue | Check |
+|-------|--------|
+| Module not found | Install all **peer** packages (React, TipTap v3, `lucide-react`). |
+| Broken images in mail | `onUpload` URLs must be reachable by recipients (not `localhost`). |
+
+MIT — see `package.json`.