react-email-studio 2.0.0

package/README.md

@@ -0,0 +1,126 @@
+# react-email-studio
+
+**Visual email editor for React** — drag-and-drop layouts and blocks, rich text, images, buttons, tables, and more. Designs save as **JSON** (`email_document`); use **`jsonToHtml()`** to generate **HTML** for preview and your ESP (SendGrid, SES, Mailgun, …).
+
+[![npm](https://img.shields.io/npm/v/react-email-studio.svg)](https://www.npmjs.com/package/react-email-studio)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- Multi-column **layout rows** and **content blocks** (heading, text/HTML, image, button, link, divider, spacer, social, video, menu, timer, table, nested layouts)
+- **Page & content** backgrounds (solid, gradient, image), responsive preview
+- **Undo / redo**, zoom, device preview modal
+- **Internationalized** UI strings (`en`, `fr`, `de`, `es`)
+- **Merge tags** support for templates
+- Tree-shakeable ESM + CJS, TypeScript types
+
+---
+
+## Installation
+
+```bash
+npm install react-email-studio
+```
+
+```bash
+pnpm add react-email-studio
+yarn add react-email-studio
+```
+
+### Peer dependencies
+
+Install these in your application (versions should satisfy `peerDependencies` in this package):
+
+`react`, `react-dom`, `lucide-react`, and 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`).
+
+---
+
+## Quick start
+
+```tsx
+import { useRef } from "react";
+import {
+  ReactEmailEditor,
+  type ReactEmailEditorRef,
+  jsonToHtml,
+} from "react-email-studio";
+
+export function App() {
+  const editorRef = useRef<ReactEmailEditorRef>(null);
+
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() =>
+          editorRef.current?.exportJson((json) => {
+            // Persist JSON (API / database)
+            fetch("/api/save-email", { method: "POST", body: json });
+          }, true)
+        }
+      >
+        Save design
+      </button>
+
+      <ReactEmailEditor
+        ref={editorRef}
+        hideTemplates
+        onReady={(api) => {
+          /* api.loadJson(existingDesign); */
+        }}
+        onUpload={async (file) => {
+          const url = await uploadToYourStorage(file); // must return a public URL
+          return url;
+        }}
+        options={{ locale: "en" }}
+      />
+    </>
+  );
+}
+
+// Generate HTML for sending (server or client)
+const html = jsonToHtml(savedDesignJson, {
+  customCSS: `/* optional extra styles */`,
+});
+```
+
+Implement **`onUpload`** so image/video uploads return URLs your recipients can load (HTTPS recommended).
+
+---
+
+## Package exports
+
+| Export | Description |
+|--------|-------------|
+| `ReactEmailEditor` | Main editor component (`forwardRef`). |
+| `ReactEmailEditorProps` | Component props type. |
+| `ReactEmailEditorRef` | Imperative API: `loadJson`, `exportJson`. |
+| `jsonToHtml` | `(design, opts?) => string` — full HTML email document. |
+| `utf8ToBase64`, `base64ToUtf8` | Encoding helpers. |
+| `EmailPreviewModal` | Standalone responsive preview modal. |
+| `emailPreviewDevices` | Device presets for preview. |
+| `EmailPreviewModalProps`, `MobilePreviewVariant` | TypeScript types. |
+| `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)**.
+
+---
+
+## Documentation in this package
+
+| File | Audience |
+|------|----------|
+| **[USER_README.md](./USER_README.md)** | User guide — editor UI, workflows, options overview, troubleshooting. |
+| **[TUTORIAL.md](./TUTORIAL.md)** | Integration tutorial — peers, save/load, Next.js/Vite, APIs, TypeScript. |
+| **README.md** (this file) | npm landing page — install, quick start, exports. |
+
+Deployment (hosting, CSP, publishing), deeper integration notes, and monorepo **`DEPLOYMENT.md`** live in the **source repository** alongside this package—clone or browse the repo for the full file.
+
+---
+
+## License
+
+MIT

package/TUTORIAL.md

@@ -0,0 +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`.

package/USER_README.md

@@ -0,0 +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`.