@standhigher/react-email-editor 0.3.0 → 0.4.1

package/docs/assets/architecture.svg

@@ -0,0 +1,84 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="1300" viewBox="0 0 1440 1300" role="img" aria-labelledby="title description" xml:lang="en"><title id="title">Project module architecture</title><desc id="description">8 connected modules: choose content → edit → preview → save or export. Content block library, Drag-and-drop canvas, Block &amp; body settings, Subject &amp; personalization, Desktop / mobile preview, Custom blocks &amp; resources, Document &amp; editing state, Email rendering &amp; validation.</desc><defs><marker id="arrow" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M1 1 L7 4.5 L1 8" fill="none" stroke="#91a2b8" stroke-width="1.6"/></marker></defs><g font-family="'PingFang SC','Helvetica Neue',Arial,sans-serif">
+<rect x="0" y="0" width="1440" height="1300" rx="0" fill="#ffffff" stroke="#ffffff"/>
+<text x="48" y="59" font-size="38" font-weight="700" fill="#152033">Project module architecture</text>
+<text x="48" y="101" font-size="23" font-weight="400" fill="#64748b">8 connected modules: choose content → edit → preview → save or export</text>
+<rect x="48" y="135" width="1344" height="88" rx="16" fill="#eff4fb" stroke="#d8e1ed"/>
+<text x="72" y="173" font-size="26" font-weight="650" fill="#152033">Embed in your application</text>
+<text x="72" y="205" font-size="22" font-weight="400" fill="#475569">Add email editing to your website, admin app or business system</text>
+<path d="M720 223 V250" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<rect x="48" y="262" width="1344" height="514" rx="20" fill="#f8fafc" stroke="#ccd7e5"/>
+<text x="72" y="305" font-size="27" font-weight="700" fill="#152033">Modules people interact with</text>
+<text x="560" y="304" font-size="21" font-weight="400" fill="#64748b">Six core capabilities for creating an email</text>
+<rect x="72" y="332" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="90" y="350" width="38" height="34" rx="9" fill="#efeaff" stroke="#efeaff"/>
+<text x="97" y="375" font-size="18" font-weight="700" fill="#6653c1">01</text>
+<text x="142" y="376" font-size="23" font-weight="650" fill="#152033">Content block library</text>
+<text x="92" y="420" font-size="20" font-weight="400" fill="#475569">Heading, text, button and image</text>
+<text x="92" y="453" font-size="20" font-weight="400" fill="#475569">Divider, spacer and custom HTML</text>
+<text x="92" y="486" font-size="20" font-weight="400" fill="#475569">Drag the content into your email</text>
+<rect x="512" y="332" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="530" y="350" width="38" height="34" rx="9" fill="#e7f1ff" stroke="#e7f1ff"/>
+<text x="537" y="375" font-size="18" font-weight="700" fill="#266ab5">02</text>
+<text x="582" y="376" font-size="23" font-weight="650" fill="#152033">Drag-and-drop canvas</text>
+<text x="532" y="420" font-size="20" font-weight="400" fill="#475569">Reorder, duplicate and delete blocks</text>
+<text x="532" y="453" font-size="20" font-weight="400" fill="#475569">Edit text and rich text directly</text>
+<text x="532" y="486" font-size="20" font-weight="400" fill="#475569">See the layout while you edit</text>
+<rect x="952" y="332" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="970" y="350" width="38" height="34" rx="9" fill="#fff1e1" stroke="#fff1e1"/>
+<text x="977" y="375" font-size="18" font-weight="700" fill="#a3652d">03</text>
+<text x="1022" y="376" font-size="23" font-weight="650" fill="#152033">Block &amp; body settings</text>
+<text x="972" y="420" font-size="20" font-weight="400" fill="#475569">Change content, colors and borders</text>
+<text x="972" y="453" font-size="20" font-weight="400" fill="#475569">Adjust width, padding and spacing</text>
+<text x="972" y="486" font-size="20" font-weight="400" fill="#475569">Set email-wide fonts and background</text>
+<rect x="72" y="545" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="90" y="563" width="38" height="34" rx="9" fill="#e7f6ef" stroke="#e7f6ef"/>
+<text x="97" y="588" font-size="18" font-weight="700" fill="#268163">04</text>
+<text x="142" y="589" font-size="23" font-weight="650" fill="#152033">Subject &amp; personalization</text>
+<text x="92" y="633" font-size="20" font-weight="400" fill="#475569">Set the email subject</text>
+<text x="92" y="666" font-size="20" font-weight="400" fill="#475569">Insert customer or store variables</text>
+<text x="92" y="699" font-size="20" font-weight="400" fill="#475569">See replacements with sample data</text>
+<rect x="512" y="545" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="530" y="563" width="38" height="34" rx="9" fill="#e7f1ff" stroke="#e7f1ff"/>
+<text x="537" y="588" font-size="18" font-weight="700" fill="#266ab5">05</text>
+<text x="582" y="589" font-size="23" font-weight="650" fill="#152033">Desktop / mobile preview</text>
+<text x="532" y="633" font-size="20" font-weight="400" fill="#475569">Switch between desktop and mobile</text>
+<text x="532" y="666" font-size="20" font-weight="400" fill="#475569">Preview resolved template variables</text>
+<text x="532" y="699" font-size="20" font-weight="400" fill="#475569">Review content and layout before sending</text>
+<rect x="952" y="545" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="970" y="563" width="38" height="34" rx="9" fill="#efeaff" stroke="#efeaff"/>
+<text x="977" y="588" font-size="18" font-weight="700" fill="#6653c1">06</text>
+<text x="1022" y="589" font-size="23" font-weight="650" fill="#152033">Custom blocks &amp; resources</text>
+<text x="972" y="633" font-size="20" font-weight="400" fill="#475569">Add business blocks, e.g. product cards</text>
+<text x="972" y="666" font-size="20" font-weight="400" fill="#475569">Customize editing UI and controls</text>
+<text x="972" y="699" font-size="20" font-weight="400" fill="#475569">Connect your image resource picker</text>
+<path d="M494 426 H504" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M944 426 H934" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M720 776 V812" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" />
+<text x="48" y="826" font-size="24" font-weight="650" fill="#475569">Shared capabilities supporting all editing modules</text>
+<path d="M720 845 V856 H386 V876" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M720 856 H1054 V876" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<rect x="48" y="889" width="642" height="153" rx="16" fill="#f3efff" stroke="#dcd1f5"/>
+<rect x="70" y="909" width="38" height="34" rx="9" fill="#e7defb" stroke="#e7defb"/>
+<text x="77" y="934" font-size="18" font-weight="700" fill="#6653c1">07</text>
+<text x="122" y="936" font-size="26" font-weight="650" fill="#40347a">Document &amp; editing state</text>
+<text x="72" y="976" font-size="21" font-weight="400" fill="#475569">Keep content, block order, styles and subject together</text>
+<text x="72" y="1010" font-size="21" font-weight="400" fill="#475569">Load, replace and reset; editor instances stay isolated</text>
+<rect x="750" y="889" width="642" height="153" rx="16" fill="#eef5ff" stroke="#cddff7"/>
+<rect x="772" y="909" width="38" height="34" rx="9" fill="#dfeaff" stroke="#dfeaff"/>
+<text x="779" y="934" font-size="18" font-weight="700" fill="#266ab5">08</text>
+<text x="824" y="936" font-size="26" font-weight="650" fill="#225897">Email rendering &amp; validation</text>
+<text x="774" y="976" font-size="21" font-weight="400" fill="#475569">Validate controls and blocks; generate email HTML</text>
+<text x="774" y="1010" font-size="21" font-weight="400" fill="#475569">Keep templates for delivery or resolve data for preview</text>
+<path d="M690 965 H738" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M369 1042 V1081" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M1071 1042 V1081" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<rect x="48" y="1094" width="642" height="137" rx="16" fill="#edf8f1" stroke="#cce4d5"/>
+<text x="72" y="1134" font-size="27" font-weight="700" fill="#286844">JSON document</text>
+<text x="72" y="1170" font-size="23" font-weight="400" fill="#475569">Your app saves the draft</text>
+<text x="72" y="1202" font-size="23" font-weight="400" fill="#475569">Load it later and continue editing</text>
+<rect x="750" y="1094" width="642" height="137" rx="16" fill="#edf5ff" stroke="#cddff7"/>
+<text x="774" y="1134" font-size="27" font-weight="700" fill="#225897">Email HTML</text>
+<text x="774" y="1170" font-size="23" font-weight="400" fill="#475569">Export templates or preview output</text>
+<text x="774" y="1202" font-size="23" font-weight="400" fill="#475569">Pass it to your email delivery system</text>
+<text x="48" y="1272" font-size="21" font-weight="400" fill="#64748b">This project builds, previews and exports emails. Your app handles storage, uploads and delivery.</text>
+</g></svg>

package/docs/assets/architecture.zh-CN.svg

@@ -0,0 +1,84 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="1300" viewBox="0 0 1440 1300" role="img" aria-labelledby="title description" xml:lang="zh-CN"><title id="title">项目模块架构图</title><desc id="description">8 个模块协同：选内容 → 编邮件 → 看预览 → 保存或导出. 内容区块库, 拖拽编辑画布, 属性与主体设置, 主题与个性化, 桌面 / 移动预览, 自定义区块与资源, 文档与编辑状态, 邮件渲染与校验.</desc><defs><marker id="arrow" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto"><path d="M1 1 L7 4.5 L1 8" fill="none" stroke="#91a2b8" stroke-width="1.6"/></marker></defs><g font-family="'PingFang SC','Helvetica Neue',Arial,sans-serif">
+<rect x="0" y="0" width="1440" height="1300" rx="0" fill="#ffffff" stroke="#ffffff"/>
+<text x="48" y="59" font-size="38" font-weight="700" fill="#152033">项目模块架构图</text>
+<text x="48" y="101" font-size="23" font-weight="400" fill="#64748b">8 个模块协同：选内容 → 编邮件 → 看预览 → 保存或导出</text>
+<rect x="48" y="135" width="1344" height="88" rx="16" fill="#eff4fb" stroke="#d8e1ed"/>
+<text x="72" y="173" font-size="26" font-weight="650" fill="#152033">接入你的应用</text>
+<text x="72" y="205" font-size="22" font-weight="400" fill="#475569">网站、运营后台或业务系统，把邮件编辑能力嵌入现有页面</text>
+<path d="M720 223 V250" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<rect x="48" y="262" width="1344" height="514" rx="20" fill="#f8fafc" stroke="#ccd7e5"/>
+<text x="72" y="305" font-size="27" font-weight="700" fill="#152033">用户直接操作的模块</text>
+<text x="560" y="304" font-size="21" font-weight="400" fill="#64748b">制作一封邮件时使用的 6 项核心能力</text>
+<rect x="72" y="332" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="90" y="350" width="38" height="34" rx="9" fill="#efeaff" stroke="#efeaff"/>
+<text x="97" y="375" font-size="18" font-weight="700" fill="#6653c1">01</text>
+<text x="142" y="376" font-size="25" font-weight="650" fill="#152033">内容区块库</text>
+<text x="92" y="420" font-size="23" font-weight="400" fill="#475569">标题、正文、按钮、图片</text>
+<text x="92" y="453" font-size="23" font-weight="400" fill="#475569">分割线、留白、自定义 HTML</text>
+<text x="92" y="486" font-size="23" font-weight="400" fill="#475569">把需要的内容拖入邮件</text>
+<rect x="512" y="332" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="530" y="350" width="38" height="34" rx="9" fill="#e7f1ff" stroke="#e7f1ff"/>
+<text x="537" y="375" font-size="18" font-weight="700" fill="#266ab5">02</text>
+<text x="582" y="376" font-size="25" font-weight="650" fill="#152033">拖拽编辑画布</text>
+<text x="532" y="420" font-size="23" font-weight="400" fill="#475569">排列、复制、删除内容区块</text>
+<text x="532" y="453" font-size="23" font-weight="400" fill="#475569">直接编辑文字与富文本</text>
+<text x="532" y="486" font-size="23" font-weight="400" fill="#475569">边编辑边查看邮件布局</text>
+<rect x="952" y="332" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="970" y="350" width="38" height="34" rx="9" fill="#fff1e1" stroke="#fff1e1"/>
+<text x="977" y="375" font-size="18" font-weight="700" fill="#a3652d">03</text>
+<text x="1022" y="376" font-size="25" font-weight="650" fill="#152033">属性与主体设置</text>
+<text x="972" y="420" font-size="23" font-weight="400" fill="#475569">修改区块内容、颜色与边框</text>
+<text x="972" y="453" font-size="23" font-weight="400" fill="#475569">调整宽度、内边距与间距</text>
+<text x="972" y="486" font-size="23" font-weight="400" fill="#475569">统一设置邮件字体与背景</text>
+<rect x="72" y="545" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="90" y="563" width="38" height="34" rx="9" fill="#e7f6ef" stroke="#e7f6ef"/>
+<text x="97" y="588" font-size="18" font-weight="700" fill="#268163">04</text>
+<text x="142" y="589" font-size="25" font-weight="650" fill="#152033">主题与个性化</text>
+<text x="92" y="633" font-size="23" font-weight="400" fill="#475569">设置邮件主题</text>
+<text x="92" y="666" font-size="23" font-weight="400" fill="#475569">插入姓名、店铺等模板变量</text>
+<text x="92" y="699" font-size="23" font-weight="400" fill="#475569">使用示例数据查看替换结果</text>
+<rect x="512" y="545" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="530" y="563" width="38" height="34" rx="9" fill="#e7f1ff" stroke="#e7f1ff"/>
+<text x="537" y="588" font-size="18" font-weight="700" fill="#266ab5">05</text>
+<text x="582" y="589" font-size="25" font-weight="650" fill="#152033">桌面 / 移动预览</text>
+<text x="532" y="633" font-size="23" font-weight="400" fill="#475569">切换桌面与手机显示效果</text>
+<text x="532" y="666" font-size="23" font-weight="400" fill="#475569">预览模板变量替换后的内容</text>
+<text x="532" y="699" font-size="23" font-weight="400" fill="#475569">发送前检查邮件内容与版式</text>
+<rect x="952" y="545" width="416" height="188" rx="16" fill="#ffffff" stroke="#d8e1ed"/>
+<rect x="970" y="563" width="38" height="34" rx="9" fill="#efeaff" stroke="#efeaff"/>
+<text x="977" y="588" font-size="18" font-weight="700" fill="#6653c1">06</text>
+<text x="1022" y="589" font-size="25" font-weight="650" fill="#152033">自定义区块与资源</text>
+<text x="972" y="633" font-size="23" font-weight="400" fill="#475569">增加商品卡片等业务区块</text>
+<text x="972" y="666" font-size="23" font-weight="400" fill="#475569">定制编辑画布和属性控件</text>
+<text x="972" y="699" font-size="23" font-weight="400" fill="#475569">接入已有图片资源选择器</text>
+<path d="M494 426 H504" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M944 426 H934" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M720 776 V812" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" />
+<text x="48" y="826" font-size="24" font-weight="650" fill="#475569">支撑所有编辑模块的共享能力</text>
+<path d="M720 845 V856 H386 V876" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M720 856 H1054 V876" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<rect x="48" y="889" width="642" height="153" rx="16" fill="#f3efff" stroke="#dcd1f5"/>
+<rect x="70" y="909" width="38" height="34" rx="9" fill="#e7defb" stroke="#e7defb"/>
+<text x="77" y="934" font-size="18" font-weight="700" fill="#6653c1">07</text>
+<text x="122" y="936" font-size="26" font-weight="650" fill="#40347a">文档与编辑状态</text>
+<text x="72" y="976" font-size="23" font-weight="400" fill="#475569">统一记录邮件内容、顺序、样式与主题</text>
+<text x="72" y="1010" font-size="23" font-weight="400" fill="#475569">支持载入、替换、重置；多个编辑器互不干扰</text>
+<rect x="750" y="889" width="642" height="153" rx="16" fill="#eef5ff" stroke="#cddff7"/>
+<rect x="772" y="909" width="38" height="34" rx="9" fill="#dfeaff" stroke="#dfeaff"/>
+<text x="779" y="934" font-size="18" font-weight="700" fill="#266ab5">08</text>
+<text x="824" y="936" font-size="26" font-weight="650" fill="#225897">邮件渲染与校验</text>
+<text x="774" y="976" font-size="23" font-weight="400" fill="#475569">检查控件值与区块配置，生成邮件 HTML</text>
+<text x="774" y="1010" font-size="23" font-weight="400" fill="#475569">保留模板供发送使用，或解析示例数据用于预览</text>
+<path d="M690 965 H738" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M369 1042 V1081" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<path d="M1071 1042 V1081" fill="none" stroke="#91a2b8" stroke-width="2.5" stroke-linejoin="round" marker-end="url(#arrow)"/>
+<rect x="48" y="1094" width="642" height="137" rx="16" fill="#edf8f1" stroke="#cce4d5"/>
+<text x="72" y="1134" font-size="27" font-weight="700" fill="#286844">JSON 文档</text>
+<text x="72" y="1170" font-size="23" font-weight="400" fill="#475569">交给应用保存草稿</text>
+<text x="72" y="1202" font-size="23" font-weight="400" fill="#475569">下次载入，继续编辑</text>
+<rect x="750" y="1094" width="642" height="137" rx="16" fill="#edf5ff" stroke="#cddff7"/>
+<text x="774" y="1134" font-size="27" font-weight="700" fill="#225897">邮件 HTML</text>
+<text x="774" y="1170" font-size="23" font-weight="400" fill="#475569">导出邮件模板或预览结果</text>
+<text x="774" y="1202" font-size="23" font-weight="400" fill="#475569">交给应用的邮件发送系统</text>
+<text x="48" y="1272" font-size="22" font-weight="400" fill="#64748b">本项目负责邮件制作、预览与导出；数据存储、文件上传、实际发信由接入应用完成。</text>
+</g></svg>

package/docs/basic-examples.md

@@ -0,0 +1,113 @@
+# Basic examples
+
+[简体中文](./basic-examples.zh-CN.md) | [API reference](./api.md) | [Advanced examples](./advanced-examples.md)
+
+Import `@standhigher/react-email-editor/styles.css` once from your global stylesheet entry. Each component example can live in its own `.tsx` file. Add `"use client"` with Next.js App Router.
+
+## 1. Empty editor and JSON saving
+
+```tsx
+import { useState } from "react";
+import { EmailEditor, useEmailEditor } from "@standhigher/react-email-editor";
+
+export function EmailComposer() {
+  const editor = useEmailEditor();
+  const [savedJson, setSavedJson] = useState("");
+
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" onClick={() => setSavedJson(editor.getJson())}>Save JSON</button>
+      <output>{savedJson ? "Saved in page state" : "Not saved yet"}</output>
+    </>
+  );
+}
+```
+
+This example saves to React state, which does not survive a page reload. Your app implements database or file persistence. getDocument() returns a detached JSON object, getJson() a formatted string, and getHtml() template HTML for a sending system.
+
+## 2. Initial content, document switching and reset
+
+```tsx
+import {
+  BLOCK_TYPES, createBlockNode, createEmailDocument,
+  EmailEditor, useEmailEditor, type EmailDocument,
+} from "@standhigher/react-email-editor";
+
+const heading = createBlockNode(BLOCK_TYPES.heading);
+if (heading) heading.controls.html = "<h1>Welcome to our newsletter</h1>";
+const initialDocument = createEmailDocument(heading ? [heading] : []);
+
+interface RestorableEditorProps {
+  savedDocument: EmailDocument;
+}
+
+export function RestorableEditor({ savedDocument }: RestorableEditorProps) {
+  const editor = useEmailEditor({ initialDocument });
+  return (
+    <>
+      <EmailEditor editor={editor} height={640} />
+      <button type="button" onClick={() => editor.setDocument(savedDocument)}>Load saved document</button>
+      <button type="button" onClick={() => editor.reset()}>Restore initial content</button>
+    </>
+  );
+}
+```
+
+Your app loads and validates savedDocument as a current v4 document. TypeScript types do not replace runtime JSON validation. initialDocument is read once; use setDocument() for later replacements. reset() restores the first initialized content, not the most recently loaded document.
+
+## 3. Body styles, variables and preview export
+
+```tsx
+import { useState } from "react";
+import {
+  BLOCK_TYPES, createBlockNode, createEmailDocument, EmailEditor, useEmailEditor,
+} from "@standhigher/react-email-editor";
+
+const text = createBlockNode(BLOCK_TYPES.text);
+if (text) text.controls.html = "<p>Hello, {{ customer_name }}, welcome to {{ store_name }}</p>";
+const initialDocument = createEmailDocument(text ? [text] : []);
+
+export function PersonalizedEditor() {
+  const [html, setHtml] = useState("");
+  const editor = useEmailEditor({
+    initialDocument,
+    body: { contentWidth: 640, contentPadding: "24px", backgroundColor: "#f7f7f7" },
+    variables: [
+      { name: "{{ store_name }}", description: "Store name", value: "Example Store" },
+      { name: "{{ customer_name }}", value: "Sam" },
+    ],
+  });
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" onClick={() => setHtml(editor.getHtml())}>Read template HTML</button>
+      <button type="button" onClick={() => setHtml(editor.getRenderedHtml())}>Read preview HTML</button>
+      <pre>{html}</pre>
+    </>
+  );
+}
+```
+
+Template export preserves variables and dots listed tokens: {{ store_name }} becomes {{ .store_name }}. Preview export substitutes Example Store and other values. The editor includes desktop and mobile preview. This example displays source in a pre element; your app can download or upload it. See [validated saving](./advanced-examples.md#1-validate-before-async-saving) for export error handling.
+
+## 4. Export without mounting the editor
+
+```ts
+import {
+  BLOCK_TYPES, createBlockNode, createEmailDocument, documentToHtml,
+} from "@standhigher/react-email-editor";
+
+const block = createBlockNode(BLOCK_TYPES.html);
+if (!block) throw new Error("HTML block is not registered");
+block.controls.html = "<p>Hello, {{.customer.name}}</p>";
+const document = createEmailDocument([block]);
+
+export const templateHtml = documentToHtml(document);
+export const previewHtml = documentToHtml(document, undefined, {
+  resolveHtmlTemplates: true,
+  templateData: { customer: { name: "Sam" } },
+});
+```
+
+Each export contains one doctype, html, head and body. Custom blocks need a shared registry; see [advanced examples](./advanced-examples.md#3-business-block-with-multiple-rich-text-regions-and-a-list).

package/docs/basic-examples.zh-CN.md

@@ -0,0 +1,113 @@
+# 基础场景示例
+
+[English](./basic-examples.md) | [API 参考](./api.zh-CN.md) | [复杂场景](./advanced-examples.zh-CN.md)
+
+在应用全局样式入口引入一次 `@standhigher/react-email-editor/styles.css`。以下每段组件示例可以独立放入一个 `.tsx` 文件；Next.js App Router 中添加 `"use client"`。
+
+## 1. 空编辑器与保存 JSON
+
+```tsx
+import { useState } from "react";
+import { EmailEditor, useEmailEditor } from "@standhigher/react-email-editor";
+
+export function EmailComposer() {
+  const editor = useEmailEditor();
+  const [savedJson, setSavedJson] = useState("");
+
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" onClick={() => setSavedJson(editor.getJson())}>保存 JSON</button>
+      <output>{savedJson ? "已保存到当前页面状态" : "尚未保存"}</output>
+    </>
+  );
+}
+```
+
+该示例保存到 React 状态，刷新后不会保留；数据库或文件持久化由应用实现。`getDocument()` 返回 JSON 对象快照，`getJson()` 返回格式化字符串，`getHtml()` 返回可交给发送系统的模板 HTML。
+
+## 2. 初始内容、切换文档与重置
+
+```tsx
+import {
+  BLOCK_TYPES, createBlockNode, createEmailDocument,
+  EmailEditor, useEmailEditor, type EmailDocument,
+} from "@standhigher/react-email-editor";
+
+const heading = createBlockNode(BLOCK_TYPES.heading);
+if (heading) heading.controls.html = "<h1>欢迎订阅</h1>";
+const initialDocument = createEmailDocument(heading ? [heading] : []);
+
+interface RestorableEditorProps {
+  savedDocument: EmailDocument;
+}
+
+export function RestorableEditor({ savedDocument }: RestorableEditorProps) {
+  const editor = useEmailEditor({ initialDocument });
+  return (
+    <>
+      <EmailEditor editor={editor} height={640} />
+      <button type="button" onClick={() => editor.setDocument(savedDocument)}>载入已保存文档</button>
+      <button type="button" onClick={() => editor.reset()}>恢复初始内容</button>
+    </>
+  );
+}
+```
+
+`savedDocument` 应由应用读取并校验为当前 v4 文档；TypeScript 类型不替代运行时 JSON 校验。`initialDocument` 只读取一次；后续切换用 `setDocument()`。`reset()` 恢复首次初始化内容，不是最近载入的文档。
+
+## 3. 主体样式、变量与预览导出
+
+```tsx
+import { useState } from "react";
+import {
+  BLOCK_TYPES, createBlockNode, createEmailDocument, EmailEditor, useEmailEditor,
+} from "@standhigher/react-email-editor";
+
+const text = createBlockNode(BLOCK_TYPES.text);
+if (text) text.controls.html = "<p>你好，{{ customer_name }}，欢迎来到 {{ store_name }}</p>";
+const initialDocument = createEmailDocument(text ? [text] : []);
+
+export function PersonalizedEditor() {
+  const [html, setHtml] = useState("");
+  const editor = useEmailEditor({
+    initialDocument,
+    body: { contentWidth: 640, contentPadding: "24px", backgroundColor: "#f7f7f7" },
+    variables: [
+      { name: "{{ store_name }}", description: "店铺名称", value: "示例店铺" },
+      { name: "{{ customer_name }}", value: "李小明" },
+    ],
+  });
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" onClick={() => setHtml(editor.getHtml())}>读取模板 HTML</button>
+      <button type="button" onClick={() => setHtml(editor.getRenderedHtml())}>读取预览 HTML</button>
+      <pre>{html}</pre>
+    </>
+  );
+}
+```
+
+模板导出保留变量，并把列出的 `{{ store_name }}` 补成 `{{ .store_name }}`；预览导出替换为示例店铺等文本。编辑器自带桌面与移动端预览。这里用 `<pre>` 展示导出源码；应用可自行下载或上传。生产导出错误处理见[校验后保存](./advanced-examples.zh-CN.md#1-校验后异步保存)。
+
+## 4. 不挂载编辑器直接导出
+
+```ts
+import {
+  BLOCK_TYPES, createBlockNode, createEmailDocument, documentToHtml,
+} from "@standhigher/react-email-editor";
+
+const block = createBlockNode(BLOCK_TYPES.html);
+if (!block) throw new Error("HTML 区块未注册");
+block.controls.html = "<p>你好，{{.customer.name}}</p>";
+const document = createEmailDocument([block]);
+
+export const templateHtml = documentToHtml(document);
+export const previewHtml = documentToHtml(document, undefined, {
+  resolveHtmlTemplates: true,
+  templateData: { customer: { name: "李小明" } },
+});
+```
+
+每份导出只有一套 doctype、html、head 和 body。自定义区块需共享注册表，见[复杂场景](./advanced-examples.zh-CN.md#3-业务区块多区域富文本与列表)。

package/docs/custom-blocks.md

@@ -8,18 +8,20 @@ This guide follows “example → parameters → return values → behavior” f
 | --- | --- |
 | `EmailControls` | Declare controls, value types, defaults, validation, and editing components. |
 | `defineBlock()` | Combine controls, styles, editing UI, and email output into a block plugin. |
-| `createEmailEditorConfig()` | Register plugins and provide block creation, document validation, and HTML export. |
+| `useEmailEditorConfig()` | Register plugins and provide block creation, document validation, and HTML export. |
 
 Built-in blocks use the same mechanism. Configuration holds no document or selection state and can be shared by multiple editors. `EmailDocument` is the source of truth for document state; the React editing session handles selection, dragging, and updates.
 
 ## Complete integration example
 
 ```tsx
+import { useState } from "react";
 import {
   EmailEditor,
   EmailControls,
   createEmailDocument,
-  createEmailEditorConfig,
+  useEmailEditorConfig,
+  useEmailEditor,
   defineBlock,
 } from "@standhigher/react-email-editor";
 import "@standhigher/react-email-editor/styles.css";
@@ -40,17 +42,12 @@ const coupon = defineBlock({
   `,
 });
 
-// Keep outside the component, or stabilize the reference with useMemo.
-const config = createEmailEditorConfig({ plugins: [coupon] });
-const initialDocument = createEmailDocument([config.createBlock(coupon.type)]);
-
 export function EmailPage() {
-  return <EmailEditor config={config} initialDocument={initialDocument} />;
+  const config = useEmailEditorConfig({ plugins: [coupon] });
+  const [initialDocument] = useState(() => createEmailDocument([config.createBlock(coupon.type)]));
+  const editor = useEmailEditor({ config, initialDocument });
+  return <EmailEditor editor={editor} />;
 }
-
-// Standalone export uses the same configuration without mounting the editor.
-const issues = config.validate(initialDocument);
-const html = config.toHtml(initialDocument);
 ```
 
 At declaration time, `controls` contains control definitions. In nodes, Canvas/Inspector props, and render contexts, it contains their values:
@@ -66,29 +63,28 @@ controls: { code: EmailControls.text({ label: "Code", defaultValue: "SAVE20" })
 controls.code // string
 ```
 
-## 1. createEmailEditorConfig(options?)
+## 1. useEmailEditorConfig(options?)
 
 ### Example
 
-```ts
-const config = createEmailEditorConfig({
-  plugins: [coupon],
-  builtins: ["heading", "text", "image", "button"],
-  pickImage: async ({ value, label, signal }) => {
-    // Open your application's asset picker; initialize with value,
-    // use label as its title, and cancel requests with signal.
-    // Return an image URL, or null when canceled.
-    return null;
-  },
-});
-
-const block = config.createBlock("my-app.coupon");
-const document = createEmailDocument([block]);
-const html = config.toHtml(document);
-const preview = config.toHtml(document, { resolveHtmlTemplates: true });
+```tsx
+function useCouponConfig() {
+  return useEmailEditorConfig({
+    plugins: [coupon],
+    builtins: ["heading", "text", "image", "button"],
+    pickImage: async ({ value, label, signal }) => {
+      // Open your application's asset picker; initialize with value,
+      // use label as its title, and cancel requests with signal.
+      // Return an image URL, or null when canceled.
+      return null;
+    },
+  });
+}
 ```
 
-### Parameters: EmailEditorConfigOptions
+Call this Hook at the top level of a React component or custom Hook. Stable `plugins`, `builtins`, and `pickImage` references retain configuration identity. Updates preserve instance documents. Removing a plugin used by a document preserves its data and produces a missing-plugin validation issue. Configuration methods `toHtml(document)` and `validate(document)` accept any document; instance methods `getHtml()` and `validate()` use the current document.
+
+### Parameters: UseEmailEditorConfigOptions
 
 All options are optional.
 
@@ -482,10 +478,10 @@ Missing plugins produce a canvas placeholder and preserve the node; email export
 | `ControlComponentProps<T>` | Single-control React editor props. |
 | `BlockPlugin/BlockPluginOptions` | Block definition and declaration options. |
 | `PluginEditorProps/PluginRenderContext` | Editing component props and rendering context. |
-| `EmailEditorConfig/EmailEditorConfigOptions` | Registration configuration and options. |
+| `EmailEditorConfig/UseEmailEditorConfigOptions` | Registration configuration and options. |
 | `ImagePickerContext/ValidationIssue` | Image picker context and validation results. |
 | `ControlOption/StyleControlConfig/BlockInspectorSection` | Options, style controls, and inspector sections. |
 | `ControlEditorProps/EditableRichTextProps` | Reusable control and rich-text component props. |
 | `EmailMarkup/EmailTools` | Email fragments and rendering helpers. |
 
-See [README](../README.md) for editor props, ref methods, body, and variables. Runnable examples: [coupon](../playground/plugins/coupon.ts), [product card](../playground/plugins/product.ts), and [shared configuration](../playground/plugins/config.ts).
+See the [API reference](./api.md) for editor Hooks, instance methods, body, and variables, and [advanced examples](./advanced-examples.md) for business integration. Runnable examples: [coupon](../playground/plugins/coupon.ts), [product card](../playground/plugins/product.ts), and [shared configuration](../playground/plugins/config.ts).

package/docs/custom-blocks.zh-CN.md

@@ -8,18 +8,20 @@
 | --- | --- |
 | `EmailControls` | 声明控件、值类型、默认值、校验和编辑组件。 |
 | `defineBlock()` | 组合控件、样式、编辑界面和邮件输出，形成一个区块插件。 |
-| `createEmailEditorConfig()` | 注册插件，提供区块创建、文档校验和 HTML 导出。 |
+| `useEmailEditorConfig()` | 注册插件，提供区块创建、文档校验和 HTML 导出。 |
 
 内置区块使用相同机制。配置不持有具体文档或选中状态，可以被多个编辑器复用。`EmailDocument` 是文档状态的事实源，React 编辑会话负责选择、拖拽和更新。
 
 ## 完整接入示例
 
 ```tsx
+import { useState } from "react";
 import {
   EmailEditor,
   EmailControls,
   createEmailDocument,
-  createEmailEditorConfig,
+  useEmailEditorConfig,
+  useEmailEditor,
   defineBlock,
 } from "@standhigher/react-email-editor";
 import "@standhigher/react-email-editor/styles.css";
@@ -40,17 +42,12 @@ const coupon = defineBlock({
   `,
 });
 
-// 放在组件外，或通过 useMemo 保持引用稳定。
-const config = createEmailEditorConfig({ plugins: [coupon] });
-const initialDocument = createEmailDocument([config.createBlock(coupon.type)]);
-
 export function EmailPage() {
-  return <EmailEditor config={config} initialDocument={initialDocument} />;
+  const config = useEmailEditorConfig({ plugins: [coupon] });
+  const [initialDocument] = useState(() => createEmailDocument([config.createBlock(coupon.type)]));
+  const editor = useEmailEditor({ config, initialDocument });
+  return <EmailEditor editor={editor} />;
 }
-
-// 独立导出也使用同一配置，无需挂载编辑器。
-const issues = config.validate(initialDocument);
-const html = config.toHtml(initialDocument);
 ```
 
 `controls` 在声明阶段保存控件定义，在节点、Canvas/Inspector Props 和渲染上下文中保存对应的值：
@@ -66,28 +63,27 @@ controls: { code: EmailControls.text({ label: "优惠码", defaultValue: "SAVE20
 controls.code // string
 ```
 
-## 1. createEmailEditorConfig(options?)
+## 1. useEmailEditorConfig(options?)
 
 ### 示例
 
-```ts
-const config = createEmailEditorConfig({
-  plugins: [coupon],
-  builtins: ["heading", "text", "image", "button"],
-  pickImage: async ({ value, label, signal }) => {
-    // 调用应用自己的素材库；使用 value 初始化，label 作标题，signal 取消请求。
-    // 返回图片 URL；取消选择时返回 null。
-    return null;
-  },
-});
-
-const block = config.createBlock("my-app.coupon");
-const document = createEmailDocument([block]);
-const html = config.toHtml(document);
-const preview = config.toHtml(document, { resolveHtmlTemplates: true });
+```tsx
+function useCouponConfig() {
+  return useEmailEditorConfig({
+    plugins: [coupon],
+    builtins: ["heading", "text", "image", "button"],
+    pickImage: async ({ value, label, signal }) => {
+      // 调用应用自己的素材库；使用 value 初始化，label 作标题，signal 取消请求。
+      // 返回图片 URL；取消选择时返回 null。
+      return null;
+    },
+  });
+}
 ```
 
-### 参数：EmailEditorConfigOptions
+配置 Hook 必须在 React 组件或自定义 Hook 顶层调用。保持 `plugins`、`builtins` 和 `pickImage` 引用稳定会保留配置引用；更新配置不会重置已有实例文档。移除仍被文档使用的插件后，校验报告缺失插件，原始数据保留。配置的 `toHtml(document)` 和 `validate(document)` 面向任意文档；实例的 `getHtml()` 和 `validate()` 面向当前文档。
+
+### 参数：UseEmailEditorConfigOptions
 
 所有参数均可选。
 
@@ -481,10 +477,10 @@ renderEmail: ({ controls, email }) => email.html`
 | `ControlComponentProps<T>` | 单控件 React 编辑组件。 |
 | `BlockPlugin/BlockPluginOptions` | 区块定义及声明参数。 |
 | `PluginEditorProps/PluginRenderContext` | 编辑组件 Props / 邮件渲染上下文。 |
-| `EmailEditorConfig/EmailEditorConfigOptions` | 注册配置及参数。 |
+| `EmailEditorConfig/UseEmailEditorConfigOptions` | 注册配置及参数。 |
 | `ImagePickerContext/ValidationIssue` | 图片资源适配器 / 校验结果。 |
 | `ControlOption/StyleControlConfig/BlockInspectorSection` | 选项 / 样式控件 / 检查器分组。 |
 | `ControlEditorProps/EditableRichTextProps` | 控件复用和富文本编辑组件 Props。 |
 | `EmailMarkup/EmailTools` | 邮件片段及工具集。 |
 
-编辑器 Props、ref 方法、body 和 variables 的完整接入见 [README](../README.zh-CN.md)。可运行示例见 [优惠券](../playground/plugins/coupon.ts)、[商品卡片](../playground/plugins/product.ts)及[统一配置](../playground/plugins/config.ts)。
+编辑器 Hooks、实例方法、body 和 variables 的完整接入见 [API 参考](./api.zh-CN.md)，业务集成见[复杂场景](./advanced-examples.zh-CN.md)。可运行示例见 [优惠券](../playground/plugins/coupon.ts)、[商品卡片](../playground/plugins/product.ts)及[统一配置](../playground/plugins/config.ts)。