@standhigher/react-email-editor 0.3.0 → 0.4.3

package/README.md

@@ -1,159 +1,53 @@
 # @standhigher/react-email-editor
 
-English | [简体中文](./README.zh-CN.md)
+English | [简体中文](https://github.com/standhigher/react-email-editor/blob/main/README.zh-CN.md)
 
-A React email template editor with drag-and-drop blocks, inline rich text, desktop/mobile previews, JSON storage, and HTML export.
+Drag content onto a canvas, style your email, preview it, then save editable JSON or export email HTML.
 
-## Installation
+## Modules and features
 
-Requires React 18 and React DOM 18. Includes ESM and TypeScript declarations.
+![Project modules and features](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.png)
+
+[Open full-size architecture diagram](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.png) · [Editable SVG](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.svg)
+
+## Install and integrate
+
+Requires React 18 and React DOM 18. Ships ESM and TypeScript declarations.
 
 ```bash
 pnpm add @standhigher/react-email-editor
 ```
 
-## Quick start
-
-Import the stylesheet once in your application and use a ref to read the document and HTML. Your application handles persistence.
-
 ```tsx
-import { useRef } from "react";
-import {
-  BLOCK_TYPES,
-  EmailEditor,
-  createBlockNode,
-  createEmailDocument,
-  type EmailEditorHandle,
-  type Variable,
-} from "@standhigher/react-email-editor";
+import { EmailEditor, useEmailEditor } from "@standhigher/react-email-editor";
 import "@standhigher/react-email-editor/styles.css";
 
-const text = createBlockNode(BLOCK_TYPES.text);
-if (text) text.controls.html = "<p>Hello, {{ store_name }}</p>";
-const initialDocument = createEmailDocument(text ? [text] : []);
-const variables: Variable[] = [
-  { name: "{{ store_name }}", description: "Store name", value: "Example Store" },
-];
-
 export function EmailPage() {
-  const editorRef = useRef<EmailEditorHandle>(null);
-
-  function save() {
-    const data = editorRef.current?.getData();
-    if (!data) return;
-    // Persist data.document in your app; use data.html to export the template.
-    console.log(data);
-  }
-
-  return (
-    <>
-      <EmailEditor
-        ref={editorRef}
-        initialDocument={initialDocument}
-        variables={variables}
-        height={720}
-      />
-      <button type="button" onClick={save}>Save</button>
-    </>
-  );
+  const editor = useEmailEditor();
+  return <EmailEditor editor={editor} height={720} />;
 }
 ```
 
-Omit `initialDocument` to start empty. In Next.js App Router, add `"use client"` to the integration component and import CSS from an allowed global stylesheet entry. When using `height="100%"`, give the parent a definite height.
-
-## Props
-
-All props are optional.
-
-| Prop | Type | Behavior |
-| --- | --- | --- |
-| `initialDocument` | `EmailDocument` | Read on first mount only. Remount with a new React `key` to switch documents. |
-| `height` | `number \| string` | Defaults to `"100%"`; numbers are pixels. |
-| `body` | `Partial<EmailBodySettings>` | Overrides email body layout, appearance, and default typography; later changes merge into the current document. Omitting a field does not restore its default. |
-| `variables` | `Variable[]` | Variables for insertion and preview. Defaults to `[]`; Personalization controls are hidden when empty. |
-| `config` | `EmailEditorConfig` | Registers plugins, resource adapters, and library order through `createEmailEditorConfig()`. |
-| `onChange` | `(document: EmailDocument) => void` | Called on document changes, including external `body` updates that change document values. |
-| `onBodyChange` | `(body: EmailBodySettings) => void` | Called for body style edits inside the editor, excluding external `body` updates. |
+With Next.js App Router, add `"use client"` to the integration component and import CSS from an allowed global stylesheet entry. Your app implements persistence, resource uploads and email delivery.
 
-Body style example: `body={{ contentWidth: 640, contentPadding: "24px" }}`. Defaults are exported as `DEFAULT_EMAIL_BODY`; normalize a partial configuration with `resolveEmailBody()`.
+## Run locally
 
-The **BODY** panel stores its settings in `EmailDocument.body` and applies them to the canvas, preview, and HTML export:
-
-- **General**: text color, link color, font family, font weight, and a link underline switch.
-- **Content**: Background, content width, Padding (`contentPadding`), and block gap. **Advanced: Border** is collapsed by default and contains border color, width, and style. Background is the single background color of the email content container; the surrounding area is white. The container is always centered. Padding applies inside the content border and is the only body padding setting; `outerPadding` has been removed.
-
-Text and links inherit BODY defaults unless explicitly formatted in the rich-text toolbar. Editing only a link URL or target preserves explicit link styles; resetting a link style restores BODY inheritance. Base font size (16px), line height (1.5), and paragraph/list spacing use internal defaults. HTML blocks preserve their source formatting; their wrapper inherits body typography without rewriting links or lists. BODY does not expose alignment or corner radius.
-
-Built-in blocks: `heading`, `text`, `button`, `image`, `divider`, `spacer`, and `html`, available through `BLOCK_TYPES`.
-
-## Save and export
-
-| Ref method | Returns |
-| --- | --- |
-| `getData()` | `{ document, json, html, renderedHtml }` |
-| `getDocument()` | An independent `EmailDocument` snapshot to persist and pass back as `initialDocument`. |
-| `getJson()` | A formatted document JSON string. |
-| `getHtml()` | A complete email HTML document preserving template expressions. |
-| `getRenderedHtml()` | A complete email HTML document with templates resolved using preview data. |
-
-Render a document without mounting the editor:
-
-```ts
-import { documentToHtml } from "@standhigher/react-email-editor";
-
-const html = documentToHtml(initialDocument, undefined, { variables });
-const previewHtml = documentToHtml(initialDocument, undefined, {
-  variables,
-  resolveHtmlTemplates: true,
-});
-```
-
-A variable's `name` is inserted verbatim; `description` and preview `value` are optional. Export adds a missing dot only to tokens matching `variables[].name` exactly, preserving whitespace: `{{ store_name }}` → `{{ .store_name }}`. Other Go template expressions remain unchanged. Preview supports a subset of Go template syntax; data precedence is block `defaultData` > `templateData` (`documentToHtml` option) > `variables`.
-
-The document format is under development. Only `version: 4` is accepted, with no automatic migration of older documents. Create data with `createEmailDocument()` and `createBlockNode()`. See [CHANGELOG](./CHANGELOG.md) for upgrade notes.
-
-## Custom blocks
-
-Declare controls and email output with `defineBlock()`, then register once:
-
-```tsx
-const coupon = defineBlock({
-  type: "my-app.coupon",
-  title: "Coupon",
-  controls: {
-    code: EmailControls.text({ label: "Code", defaultValue: "SAVE20" }),
-  },
-  renderEmail: ({ controls, email }) => email.html`<p>${controls.code}</p>`,
-});
-const config = createEmailEditorConfig({ plugins: [coupon] });
-
-<EmailEditor config={config} />;
-const block = config.createBlock("my-app.coupon");
-const html = config.toHtml(createEmailDocument([block]));
-```
-
-Import `defineBlock`, `EmailControls`, and `createEmailEditorConfig` from the package. Control values are inferred; the inspector and canvas work automatically. Plugins support rich text, editable lists, image resource adapters, custom control components, and optional React `Inspector` / `Canvas` components. `EditableRichText` supports multiple editing regions, while `ControlEditor` reuses declared controls inside custom inspectors.
-
-`config.validate(document)` returns `ValidationIssue[]` with block IDs and control paths for export preflight. Number ranges, options, URL/image protocols, list counts, and custom validation also apply to the inspector and email export. Custom Canvas/Inspector components can call `setControls(patch)` to update related controls in one document change and one `onChange` callback. Declaration metadata is copied and frozen, parsed controls are reused within each context, and `onChange` / `onBodyChange` receive independent data snapshots.
-
-The editor and standalone export share one configuration. Use `builtins` to filter and order the library; replacing a built-in requires `override: true`. Declarations, runtime contexts, and persisted nodes all use `controls`. Documents use v4, with no old-data compatibility. The old `blocks`, `defaultFields`, `inlineEdit`, and `render()` integration is removed. See the [custom block API guide](./docs/custom-blocks.md) ([简体中文](./docs/custom-blocks.zh-CN.md)) and runnable `playground/plugins/` examples.
-
-## Local development
-
-Node.js 22.18+ and pnpm are recommended:
+Use Node.js 24 LTS (`.nvmrc`; at least 22.18 for the complete test suite) and pnpm 10.16.1 (`packageManager`):
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm dev
 ```
 
-Open [http://localhost:5173](http://localhost:5173). The playground loads `src/` directly; reuse an existing server. Validation:
+Open [http://localhost:5173](http://localhost:5173); reuse an existing server when available. See [development and local linking](https://github.com/standhigher/react-email-editor/blob/main/docs/api.md#development-and-local-linking) for build and validation commands.
 
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-node --test tests/*.test.mjs tests/*.test.ts
-```
+## Documentation
+
+- [API reference](https://github.com/standhigher/react-email-editor/blob/main/docs/api.md): every public export, parameter, default and type.
+- [Basic examples](https://github.com/standhigher/react-email-editor/blob/main/docs/basic-examples.md): initial content, saving/loading, body styles, variables and preview.
+- [Advanced examples](https://github.com/standhigher/react-email-editor/blob/main/docs/advanced-examples.md): validated saving, multiple instances, custom blocks, multiple editing regions, resource adapters and standalone export.
+- [Custom block guide](https://github.com/standhigher/react-email-editor/blob/main/docs/custom-blocks.md): detailed controls, plugins and rendering helpers.
+- [Release guide](https://github.com/standhigher/react-email-editor/blob/main/docs/release.md): package checks and manual npm publishing.
+- [Changelog](https://github.com/standhigher/react-email-editor/blob/main/docs/changelog.md).
 
-For local consumers, use `link:../react-email-editor`, run `pnpm build` first, and keep `pnpm build:watch` running to update `dist/`. Both projects must share one React instance. Vite can use `resolve.dedupe: ["react", "react-dom"]`; Next.js can use `transpilePackages: ["@standhigher/react-email-editor"]`, with Turbopack's `root` covering the linked directory.
+The document format is under development. Only `version: 4` is supported, without automatic migration of older documents.

package/README.zh-CN.md

@@ -1,159 +1,53 @@
 # @standhigher/react-email-editor
 
-[English](./README.md) | 简体中文
+[English](https://github.com/standhigher/react-email-editor/blob/main/README.md) | 简体中文
 
-React 邮件模板编辑器，支持拖拽区块、画布富文本编辑、桌面/移动预览、JSON 保存和 HTML 导出。
+把内容拖进画布，调整邮件外观，预览后保存为可继续编辑的 JSON 或导出邮件 HTML。
 
-## 安装
+## 模块架构图
 
-需要 React 18 和 React DOM 18。提供 ESM 和 TypeScript 类型。
+![项目模块架构图：8 个模块及对应功能](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.zh-CN.png)
+
+[查看高清架构图](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.zh-CN.png) · [可编辑 SVG](https://cdn.jsdelivr.net/npm/@standhigher/react-email-editor@0.4.1/docs/assets/architecture.zh-CN.svg)
+
+## 安装与最小接入
+
+需要 React 18 和 React DOM 18；包提供 ESM 和 TypeScript 类型。
 
 ```bash
 pnpm add @standhigher/react-email-editor
 ```
 
-## 基本接入
-
-在应用入口引入一次样式，通过 `ref` 读取文档和 HTML；保存逻辑由应用实现。
-
 ```tsx
-import { useRef } from "react";
-import {
-  BLOCK_TYPES,
-  EmailEditor,
-  createBlockNode,
-  createEmailDocument,
-  type EmailEditorHandle,
-  type Variable,
-} from "@standhigher/react-email-editor";
+import { EmailEditor, useEmailEditor } from "@standhigher/react-email-editor";
 import "@standhigher/react-email-editor/styles.css";
 
-const text = createBlockNode(BLOCK_TYPES.text);
-if (text) text.controls.html = "<p>你好，{{ store_name }}</p>";
-const initialDocument = createEmailDocument(text ? [text] : []);
-const variables: Variable[] = [
-  { name: "{{ store_name }}", description: "店铺名称", value: "示例店铺" },
-];
-
 export function EmailPage() {
-  const editorRef = useRef<EmailEditorHandle>(null);
-
-  function save() {
-    const data = editorRef.current?.getData();
-    if (!data) return;
-    // 将 data.document 保存到应用，data.html 用于邮件模板导出。
-    console.log(data);
-  }
-
-  return (
-    <>
-      <EmailEditor
-        ref={editorRef}
-        initialDocument={initialDocument}
-        variables={variables}
-        height={720}
-      />
-      <button type="button" onClick={save}>保存</button>
-    </>
-  );
+  const editor = useEmailEditor();
+  return <EmailEditor editor={editor} height={720} />;
 }
 ```
 
-省略 `initialDocument` 即为空编辑器。Next.js App Router 中，接入组件需声明 `"use client"`，CSS 在应用允许的全局样式入口引入。使用 `height="100%"` 时，父容器需要有明确高度。
-
-## 常用参数
-
-所有 Props 均可选。
-
-| 参数 | 类型 | 行为 |
-| --- | --- | --- |
-| `initialDocument` | `EmailDocument` | 仅首次挂载读取；切换文档时通过新的 React `key` 重新挂载。 |
-| `height` | `number \| string` | 默认 `"100%"`；数字为 px。 |
-| `body` | `Partial<EmailBodySettings>` | 覆盖邮件主体的布局、外观和默认排版，后续更新合并到当前文档；省略字段不会恢复默认值。 |
-| `variables` | `Variable[]` | 插入和预览变量；默认 `[]`，为空时隐藏 Personalization 入口。 |
-| `config` | `EmailEditorConfig` | 通过 `createEmailEditorConfig({ plugins })` 注册区块、资源适配器和区块库顺序。 |
-| `onChange` | `(document: EmailDocument) => void` | 文档变化时触发，包括实际改变文档值的外部 `body` 更新。 |
-| `onBodyChange` | `(body: EmailBodySettings) => void` | 编辑器内修改邮件主体配置时触发，外部 `body` 更新不触发。 |
+Next.js App Router 的接入组件需声明 `"use client"`；样式在应用允许的全局样式入口引入。保存、上传资源与发送邮件由你的应用实现。
 
-邮件主体示例：`body={{ contentWidth: 640, contentPadding: "24px" }}`。默认值通过 `DEFAULT_EMAIL_BODY` 导出；可使用 `resolveEmailBody()` 归一化部分配置。
+## 本地启动
 
-**BODY** 面板的配置存于 `EmailDocument.body`，同步用于画布、预览和最终邮件 HTML：
-
-- **General**：文字颜色、链接颜色、字体、字重和链接下划线开关。
-- **Content**：Background、内容宽度、Padding（`contentPadding`）和区块间距。默认折叠的 **Advanced: Border** 包含边框颜色、宽度和样式。Background 是唯一的邮件主体内容容器背景色，外侧区域为白色，主体固定居中。Padding 作用于内容边框内部，是唯一的主体内边距配置；已移除 `outerPadding`。
-
-文字和链接默认继承 BODY 配置，富文本工具栏中单独设置的格式优先。仅修改链接 URL 或打开方式会保留显式链接样式；重置链接样式后恢复继承 BODY。基础字号（16px）、行高（1.5）以及段落、列表间距使用内部默认值。HTML 区块保留源码格式，外层继承主体排版，不改写内部链接和列表。BODY 不提供对齐和圆角配置。
-
-内置区块：`heading`、`text`、`button`、`image`、`divider`、`spacer`、`html`，均可通过 `BLOCK_TYPES` 引用。
-
-## 保存与导出
-
-| Ref 方法 | 返回值 |
-| --- | --- |
-| `getData()` | `{ document, json, html, renderedHtml }` |
-| `getDocument()` | 独立的 `EmailDocument` 快照，可存储后传回 `initialDocument`。 |
-| `getJson()` | 格式化的文档 JSON 字符串。 |
-| `getHtml()` | 保留模板表达式的完整邮件 HTML。 |
-| `getRenderedHtml()` | 使用预览数据解析模板后的完整邮件 HTML。 |
-
-不挂载编辑器时，也可直接渲染文档：
-
-```ts
-import { documentToHtml } from "@standhigher/react-email-editor";
-
-const html = documentToHtml(initialDocument, undefined, { variables });
-const previewHtml = documentToHtml(initialDocument, undefined, {
-  variables,
-  resolveHtmlTemplates: true,
-});
-```
-
-变量的 `name` 原样插入，`description` 和预览值 `value` 可选。导出时仅对与 `variables[].name` 原文精确匹配的 token 补点并保留空格，如 `{{ store_name }}` → `{{ .store_name }}`；其他 Go template 表达式保持原样。预览支持部分 Go template 语法，数据优先级为区块 `defaultData` > `templateData`（`documentToHtml` 选项）> `variables`。
-
-当前文档格式仍处于开发阶段，仅接受 `version: 4`，不自动迁移旧文档。使用 `createEmailDocument()` 和 `createBlockNode()` 创建数据。升级差异见 [CHANGELOG](./CHANGELOG.md)。
-
-## 自定义区块
-
-使用 `defineBlock()` 声明控件及 `renderEmail()`，通过 `createEmailEditorConfig()` 注册：
-
-```tsx
-const coupon = defineBlock({
-  type: "my-app.coupon",
-  title: "优惠券",
-  controls: {
-    code: EmailControls.text({ label: "优惠码", defaultValue: "SAVE20" }),
-  },
-  renderEmail: ({ controls, email }) => email.html`<p>${controls.code}</p>`,
-});
-const config = createEmailEditorConfig({ plugins: [coupon] });
-
-<EmailEditor config={config} />;
-const block = config.createBlock("my-app.coupon");
-const html = config.toHtml(createEmailDocument([block]));
-```
-
-从包入口导入 `defineBlock`、`EmailControls`、`createEmailEditorConfig`。控件值自动推导，默认生成检查器和画布，支持富文本、列表、图片资源适配器、自定义控件组件及 React `Inspector` / `Canvas`。`EditableRichText` 支持多区域编辑，`ControlEditor` 可在自定义检查器复用声明的控件。
-
-`config.validate(document)` 返回带区块 ID 和控件路径的 `ValidationIssue[]`，用于导出前预检；数字范围、选项、URL/图片协议、列表数量和业务校验也用于检查器及邮件导出。自定义 Canvas/Inspector 可用 `setControls(patch)` 一次更新多个关联控件值并触发一次 `onChange`。声明元数据采用隔离冻结快照，控件值解析结果在每次上下文中复用，`onChange` / `onBodyChange` 返回独立数据快照。
-
-编辑器与独立导出共用配置；`builtins` 可筛选和排序内置区块，覆盖内置区块必须显式声明 `override: true`。声明、运行时和持久化节点统一使用 `controls`；邮件文档为 v4，不兼容旧数据，不保留旧 `blocks`、`defaultFields`、`inlineEdit` 或 `render()` 接入方式。完整接入、类型、渲染工具和异常规则见[自定义区块 API 文档](./docs/custom-blocks.zh-CN.md)（[English](./docs/custom-blocks.md)），可运行示例见 `playground/plugins/`。
-
-## 本地开发
-
-建议 Node.js 22.18+，使用 pnpm：
+推荐 Node.js 24 LTS（`.nvmrc`；完整测试最低需要 22.18）和 pnpm 10.16.1（`packageManager`）：
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm dev
 ```
 
-打开 [http://localhost:5173](http://localhost:5173)。playground 直接加载 `src/`，已有服务时复用。验证命令：
+打开 [http://localhost:5173](http://localhost:5173)，已有服务时优先复用。构建与校验命令见 [API 文档的开发说明](https://github.com/standhigher/react-email-editor/blob/main/docs/api.zh-CN.md#开发与本地联调)。
 
-```bash
-pnpm typecheck
-pnpm lint
-pnpm build
-node --test tests/*.test.mjs tests/*.test.ts
-```
+## 文档
+
+- [API 参考](https://github.com/standhigher/react-email-editor/blob/main/docs/api.zh-CN.md)：所有公共导出、参数、默认值与类型。
+- [基础场景](https://github.com/standhigher/react-email-editor/blob/main/docs/basic-examples.zh-CN.md)：初始内容、保存恢复、主体样式、变量及预览。
+- [复杂场景](https://github.com/standhigher/react-email-editor/blob/main/docs/advanced-examples.zh-CN.md)：校验后保存、多实例、自定义区块、多区域编辑、资源适配与独立导出。
+- [自定义区块指南](https://github.com/standhigher/react-email-editor/blob/main/docs/custom-blocks.zh-CN.md)：控件、插件和渲染工具的完整说明。
+- [发布指南](https://github.com/standhigher/react-email-editor/blob/main/docs/release.zh-CN.md)：发布包校验与本地手动发布。
+- [更新记录](https://github.com/standhigher/react-email-editor/blob/main/docs/changelog.zh-CN.md)。
 
-本地消费方可使用 `link:../react-email-editor`；先运行 `pnpm build`，再运行 `pnpm build:watch` 持续生成 `dist/`。两个项目需共用一个 React 实例；Vite 可按需设置 `resolve.dedupe: ["react", "react-dom"]`，Next.js 可设置 `transpilePackages: ["@standhigher/react-email-editor"]`，Turbopack 的 `root` 需覆盖链接目录。
+文档格式仍处于开发阶段，当前只支持 `version: 4`，不自动迁移旧版文档。