@standhigher/react-email-editor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Standhigher Tech Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+# @standhigher/react-email-editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [简体中文](./README.zh-CN.md)
+
+A React email editor with drag-and-drop blocks, inline rich text, and desktop/mobile previews. Store content as JSON and export email HTML through a component ref.
+
+## Installation and integration
+
+Requires React 18 and React DOM 18. The package provides an ESM entry and TypeScript declarations.
+
+```bash
+pnpm add @standhigher/react-email-editor
+```
+
+Import the stylesheet once in your application. This example renders an empty editor and reads its current data:
+
+```tsx
+import { useRef } from "react";
+import {
+  EmailEditor,
+  type EmailEditorHandle,
+} from "@standhigher/react-email-editor";
+import "@standhigher/react-email-editor/styles.css";
+
+export function EmailPage() {
+  const editorRef = useRef<EmailEditorHandle>(null);
+
+  function readData() {
+    const data = editorRef.current?.getData();
+    if (!data) return;
+    // Pass data.document, data.json, data.html, or data.renderedHtml
+    // to your application's save or export handler.
+    console.log(data);
+  }
+
+  return (
+    <>
+      <EmailEditor ref={editorRef} height={720} />
+      <button type="button" onClick={readData}>Read data</button>
+    </>
+  );
+}
+```
+
+Saving is handled by your application. In Next.js App Router, put this integration in a Client Component with `"use client"`. When using `height="100%"`, give its parent a definite height.
+
+## Local development
+
+Use pnpm and a current Node.js LTS release; Node.js 22.18+ is recommended for the repository's tooling and TypeScript tests.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+Open [http://localhost:5173](http://localhost:5173). The playground loads `src/` directly with hot reload; no initial build is needed. It is not included in the published package. Reuse an existing development server when one is already running.
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm dev` | Start the local playground on port 5173. |
+| `pnpm build` | Generate ESM, type declarations, and CSS in `dist/`. |
+| `pnpm build:watch` | Rebuild `dist/` when files in `src/` change; does not start a preview server. |
+| `pnpm typecheck` | Type-check the library and playground. |
+
+To integrate with another local project, set its dependency to the library's root directory, adjusting the relative path as needed:
+
+```json
+{
+  "dependencies": {
+    "@standhigher/react-email-editor": "link:../react-email-editor"
+  }
+}
+```
+
+Run `pnpm build` in this repository first, then keep `pnpm build:watch` running during development. In the consuming project, run `pnpm install` and use its development server. Package imports, including CSS, resolve to `dist/`.
+
+Both projects must resolve the same React instance. For Vite consumers, use `resolve.dedupe: ["react", "react-dom"]` if needed. Next.js consumers can use `transpilePackages: ["@standhigher/react-email-editor"]`; when an external link is used with Turbopack, `turbopack.root` must include both projects.
+
+## Component props
+
+All props are optional. Types are exported from `@standhigher/react-email-editor`.
+
+| Prop | Type | Default / behavior |
+| --- | --- | --- |
+| `initialDocument` | `EmailDocument` | Empty document. Read only on the first mount. |
+| `global` | `Partial<EmailGlobalSettings>` | No external overrides. Supplied fields override the initial document's global settings; later updates merge into the current document. |
+| `blocks` | `BlockDefinition[]` | `[]`. Adds custom block types; matching types replace built-in definitions. Other built-in blocks remain available. |
+| `variables` | `Variable[]` | `[]`. Variables available for insertion and preview substitution. |
+| `height` | `number \| string` | `"100%"`. A number is interpreted as pixels; a string is a CSS height. |
+| `onChange` | `(document: EmailDocument) => void` | Called when the document changes, including edits, reset, and external global updates that change its values. |
+| `onGlobalChange` | `(global: EmailGlobalSettings) => void` | Called when global settings are edited in the editor. External `global` updates and reset do not call it. |
+
+Reset restores the initial document snapshot and reapplies the current `global` overrides. To load a different document, remount with a new React `key`, for example `<EmailEditor key={documentId} initialDocument={document} />`. Changing `initialDocument` alone does not replace the open document. Omitting a previously supplied `global` field does not restore its default.
+
+## Configuration
+
+### Document
+
+Use `createEmailDocument()` and `createBlockNode()` to populate defaults:
+
+```tsx
+import {
+  BLOCK_TYPES,
+  EmailEditor,
+  createBlockNode,
+  createEmailDocument,
+  type Variable,
+} from "@standhigher/react-email-editor";
+
+const text = createBlockNode(BLOCK_TYPES.text);
+if (text) text.fields.html = "<p>Hello {{  store_name }}</p>";
+
+export const initialDocument = createEmailDocument(text ? [text] : []);
+initialDocument.subject = "Welcome";
+
+const variables: Variable[] = [
+  { name: "{{  store_name }}", description: "Store name", value: "Demo Store" },
+];
+
+export function TemplateEmailPage() {
+  return (
+    <EmailEditor
+      initialDocument={initialDocument}
+      variables={variables}
+      height={720}
+    />
+  );
+}
+```
+
+Pass both `initialDocument` and `variables` as shown so the token has a preview value and can gain its missing dot on export. `createBlockNode()` returns `null` for an unknown block type. Built-in types are `heading`, `text`, `button`, `image`, `divider`, `spacer`, and `html`, also available through `BLOCK_TYPES`.
+
+| Document field | Type | Description |
+| --- | --- | --- |
+| `version` | `typeof DOCUMENT_VERSION` | Current version: `1`. Set by `createEmailDocument()`. |
+| `subject` | `string` (optional) | Email subject. The editor input is limited to 128 characters. |
+| `global` | `EmailGlobalSettings` | Global email appearance; defaults are populated by the helper. |
+| `blocks` | `EmailBlockNode[]` | Ordered nodes, each with a unique `id`, a `type`, and `fields`, plus optional `style` and preview `defaultData`. |
+
+The document format is under development; older block fields are not migrated automatically. See the [document types](./src/types/document.ts) for the full model.
+
+### Global styles
+
+Pass partial settings through `global`, for example `<EmailEditor global={{ contentWidth: 640, outerPadding: "24px" }} />`. `DEFAULT_EMAIL_GLOBAL` exposes all defaults; `resolveEmailGlobal()` fills missing values and normalizes input.
+
+These settings control email content. Editor selection outlines and toolbars are not included in exported HTML.
+
+| Parameter | Type / values | Default | Description |
+| --- | --- | --- | --- |
+| `contentWidth` | `number` | `600` | Content width in pixels, rounded and clamped to 320–900. |
+| `contentAlign` | `"left" \| "center" \| "right"` | `"center"` | Horizontal position of the content. |
+| `backgroundColor` | `string` | `"#ffffff"` | Outer email background. |
+| `contentBackgroundColor` | `string` | `"#ffffff"` | Content background. |
+| `contentPadding` | `string` | `"0px"` | Content inner spacing. |
+| `outerPadding` | `string` | `"0px"` | Spacing outside the content. |
+| `blockGap` | `string` | `"4px"` | Gap between blocks. |
+| `textColor` | `string` | `"#000000"` | Default text color. |
+| `textAlign` | `"left" \| "center" \| "right" \| "justify"` | `"left"` | Default text alignment. |
+| `fontFamily` | `string` | `"Arial, Helvetica, sans-serif"` | Default font stack. |
+| `fontWeight` | `"normal" \| "bold"` | `"normal"` | Default font weight. |
+| `defaultFontSize` | `string` | `"16px"` | Default font size. |
+| `defaultLineHeight` | `string` | `"1.5"` | Default line height. |
+| `paragraphSpacing` | `string` | `"6px"` | Gap between adjacent top-level paragraphs. |
+| `listSpacing` | `string` | `"4px"` | Top and bottom margins of the entire list (`ul` / `ol`). |
+| `listIndent` | `string` | `"22px"` | List indentation. |
+| `linkColor` | `string` | `"#005bd3"` | Default link color. |
+| `linkDecoration` | `"underline" \| "none"` | `"underline"` | Default link decoration. |
+| `borderWidth` | `string` | `"0px"` | Content border width. |
+| `borderStyle` | `"none" \| "solid" \| "dashed" \| "dotted"` | `"solid"` | Content border style. |
+| `borderColor` | `string` | `"#000000"` | Content border color. |
+| `borderRadius` | `string` | `"0px"` | One radius or four, ordered top-left, top-right, bottom-right, bottom-left. |
+
+Use CSS length strings such as `"16px"` for spacing and sizes. Padding accepts shorthand such as `"12px 24px"`; line height also accepts a unitless value. Desktop canvas and preview follow `contentWidth`; mobile uses a 360px viewport.
+
+Global spacing and length settings accept non-negative values in `px`, `em`, `rem`, or `%`; unitless lengths are normalized to px, except for line height. Unsupported values such as negative lengths, `calc()`, `var()`, `vh`, or `vw` fall back to the corresponding global default.
+
+### Variables and template data
+
+```tsx
+import type { Variable } from "@standhigher/react-email-editor";
+
+export const variables: Variable[] = [
+  { name: "{{  store_name }}", description: "Store name", value: "Demo Store" },
+];
+```
+
+Pass this array through `variables` on `EmailEditor`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Required. Token displayed and inserted as written, including spaces. Example: `{{  store_name }}`. |
+| `description` | `string` (optional) | Secondary text in the variable menu; omitted when empty or absent. |
+| `value` | `string` (optional) | Replacement text used in previews. |
+
+Tokens may include a leading dot. Template HTML export preserves spaces and adds a missing dot only when the token exactly matches `variables[].name`, including spaces: `{{  store_name }}` becomes `{{  .store_name }}`. Other Go template actions are left unchanged. Export does not substitute preview values by default.
+
+Use a block node's `defaultData: Record<string, unknown>` for structured preview data, including arrays for `{{range .products}}`. Block data overrides variables with the same name. Preview resolution applies to every block's rendered HTML, including custom blocks. Write template expressions directly in an HTML block's `fields.html`; the preview renderer supports a subset of Go template syntax.
+
+### Block configuration
+
+Block node styles are grouped by purpose:
+
+| Style group | Purpose |
+| --- | --- |
+| `style.dimension` | Container `padding`, outer spacing via `margin`, and optional `height` in px. Height acts as a minimum including padding. |
+| `style.decorations` | Container background, border, and corner radius. |
+| `style.typography` | Block text styles overriding global typography. |
+| `style.element` | Element-specific styles for buttons, images, and dividers, such as size and alignment. |
+
+Heading and Text blocks start with `16px` padding. HTML blocks retain explicitly authored inline styles. See [EmailBlockStyle](./src/types/document.ts) for individual fields.
+
+To add a custom block, pass a stable `BlockDefinition[]` through `blocks`. `type`, `title`, and `render(ctx)` are required. Optional `fields` and `styleFields` configure the inspector; `defaultFields`, `defaultStyle`, and `defaultData` initialize new nodes. `render(ctx)` returns HTML and receives `mode: "canvas" | "email"`.
+
+```tsx
+import { EmailEditor, type BlockDefinition } from "@standhigher/react-email-editor";
+
+const customBlocks: BlockDefinition[] = [{
+  type: "notice",
+  title: "Notice",
+  defaultStyle: { dimension: { padding: "16px" } },
+  render: () => '<p style="margin:0;color:#555555;">Thanks for subscribing.</p>',
+}];
+
+export function CustomEmailPage() {
+  return <EmailEditor blocks={customBlocks} height={720} />;
+}
+```
+
+By default, common container spacing and decoration controls are added to custom blocks. Set `exactStyleFields: true` to show only the supplied style fields; existing node styles still apply when rendering. Full definitions: [BlockDefinition, FieldConfig, and StyleFieldConfig](./src/types/block.ts).
+
+## Reading and exporting data
+
+Call these methods through `useRef<EmailEditorHandle>(null)`:
+
+| Method | Return type | Description |
+| --- | --- | --- |
+| `getData()` | `EmailEditorData` | Returns `{ document, json, html, renderedHtml }`. |
+| `getDocument()` | `EmailDocument` | Independent document snapshot for storage or later editing. |
+| `getJson()` | `string` | Formatted document JSON. |
+| `getHtml()` | `string` | Complete email HTML. Template actions stay in place; only tokens from `variables` gain a missing dot. |
+| `getRenderedHtml()` | `string` | Complete email HTML with templates resolved using variables and block preview data. |
+
+Mutating a returned document snapshot does not change the editor. Use `onChange` to subscribe to document changes.
+
+For rendering without mounting the editor, use `documentToHtml(document, definitions?, options?)`. Definitions default to `DEFAULT_BLOCKS`; include custom definitions when the document uses them. `options` accepts `resolveHtmlTemplates` (default `false`), `variables`, and `templateData`. When templates stay unresolved, `variables` supplies the only tokens that gain a missing dot. When resolving, data precedence is block `defaultData` over `templateData` over `variables`.

package/README.zh-CN.md

@@ -0,0 +1,245 @@
+# @standhigher/react-email-editor
+
+[English](./README.md) | 简体中文
+
+React 邮件编辑器，支持区块拖拽、富文本编辑和桌面/移动预览。内容以 JSON 保存，通过组件 ref 导出邮件 HTML。
+
+## 安装与接入
+
+需要 React 18 和 React DOM 18。组件库提供 ESM 入口和 TypeScript 类型声明。
+
+```bash
+pnpm add @standhigher/react-email-editor
+```
+
+在应用中引入一次样式。以下示例展示空编辑器，并读取当前数据：
+
+```tsx
+import { useRef } from "react";
+import {
+  EmailEditor,
+  type EmailEditorHandle,
+} from "@standhigher/react-email-editor";
+import "@standhigher/react-email-editor/styles.css";
+
+export function EmailPage() {
+  const editorRef = useRef<EmailEditorHandle>(null);
+
+  function readData() {
+    const data = editorRef.current?.getData();
+    if (!data) return;
+    // 将 data.document、data.json、data.html 或 data.renderedHtml
+    // 交给应用自己的保存或导出逻辑。
+    console.log(data);
+  }
+
+  return (
+    <>
+      <EmailEditor ref={editorRef} height={720} />
+      <button type="button" onClick={readData}>读取数据</button>
+    </>
+  );
+}
+```
+
+保存逻辑由接入方实现。Next.js App Router 中，接入编辑器的组件需使用 `"use client"`。使用 `height="100%"` 时，父容器需要有明确高度。
+
+## 本地启动
+
+使用 pnpm 和当前受支持的 Node.js LTS；建议使用 Node.js 22.18 或更新版本，以兼容仓库工具链和 TypeScript 测试。
+
+```bash
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+打开 [http://localhost:5173](http://localhost:5173)。playground 直接加载 `src/` 并支持热更新，无需提前构建，也不进入发布包。已有开发服务时直接复用。
+
+| 命令 | 用途 |
+| --- | --- |
+| `pnpm dev` | 启动本地 playground，端口为 5173。 |
+| `pnpm build` | 在 `dist/` 生成 ESM、类型声明和 CSS。 |
+| `pnpm build:watch` | 监听 `src/` 改动并重新构建 `dist/`，不启动预览服务。 |
+| `pnpm typecheck` | 检查组件库和 playground 的类型。 |
+
+在另一个本地项目联调时，将其依赖指向组件库根目录，按实际位置调整相对路径：
+
+```json
+{
+  "dependencies": {
+    "@standhigher/react-email-editor": "link:../react-email-editor"
+  }
+}
+```
+
+先在本仓库执行 `pnpm build`，持续开发时保持 `pnpm build:watch` 运行。消费方执行 `pnpm install`，并使用自己的开发服务。包入口与 CSS 均从 `dist/` 读取。
+
+两个项目应使用同一个 React 实例。Vite 消费方可按需设置 `resolve.dedupe: ["react", "react-dom"]`。Next.js 消费方可设置 `transpilePackages: ["@standhigher/react-email-editor"]`；使用 Turbopack 且链接目录在项目外时，`turbopack.root` 需覆盖两个项目。
+
+## 组件参数
+
+所有 Props 均为可选项，相关类型从 `@standhigher/react-email-editor` 导出。
+
+| 参数 | 类型 | 默认值 / 行为 |
+| --- | --- | --- |
+| `initialDocument` | `EmailDocument` | 默认空文档，仅在首次挂载时读取。 |
+| `global` | `Partial<EmailGlobalSettings>` | 默认无外部覆盖。传入字段覆盖初始文档的全局设置；后续更新会合并到当前文档。 |
+| `blocks` | `BlockDefinition[]` | `[]`。新增自定义区块；同名 `type` 覆盖内置定义，其余内置区块保留。 |
+| `variables` | `Variable[]` | `[]`。用于插入和预览替换的变量列表。 |
+| `height` | `number \| string` | `"100%"`。数字按 px 处理，字符串使用 CSS 高度值。 |
+| `onChange` | `(document: EmailDocument) => void` | 文档变化时触发，包括编辑、重置，以及实际改变文档值的外部全局设置更新。 |
+| `onGlobalChange` | `(global: EmailGlobalSettings) => void` | 在编辑器中修改全局设置时触发；外部 `global` 更新和重置不触发此回调。 |
+
+Reset 恢复首次初始化的文档快照，并重新应用当前 `global` 覆盖项。切换文档时使用新的 React `key` 重新挂载，例如 `<EmailEditor key={documentId} initialDocument={document} />`；仅修改 `initialDocument` 不会替换已打开的文档。省略之前传入的某个 `global` 字段，不会将其恢复为默认值。
+
+## 配置说明
+
+### 文档配置
+
+通过 `createEmailDocument()` 和 `createBlockNode()` 补齐默认值：
+
+```tsx
+import {
+  BLOCK_TYPES,
+  EmailEditor,
+  createBlockNode,
+  createEmailDocument,
+  type Variable,
+} from "@standhigher/react-email-editor";
+
+const text = createBlockNode(BLOCK_TYPES.text);
+if (text) text.fields.html = "<p>你好，{{  store_name }}</p>";
+
+export const initialDocument = createEmailDocument(text ? [text] : []);
+initialDocument.subject = "欢迎订阅";
+
+const variables: Variable[] = [
+  { name: "{{  store_name }}", description: "店铺名称", value: "示例店铺" },
+];
+
+export function TemplateEmailPage() {
+  return (
+    <EmailEditor
+      initialDocument={initialDocument}
+      variables={variables}
+      height={720}
+    />
+  );
+}
+```
+
+如示例所示，同时传入 `initialDocument` 和 `variables`，使变量拥有预览值，并能在导出时补点。`createBlockNode()` 遇到未知类型时返回 `null`。内置区块有 `heading`、`text`、`button`、`image`、`divider`、`spacer` 和 `html`，可通过 `BLOCK_TYPES` 引用。
+
+| 文档字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `version` | `typeof DOCUMENT_VERSION` | 当前版本为 `1`，由 `createEmailDocument()` 填充。 |
+| `subject` | `string`，可选 | 邮件主题，编辑器输入上限为 128 个字符。 |
+| `global` | `EmailGlobalSettings` | 邮件全局样式，创建函数会补齐默认值。 |
+| `blocks` | `EmailBlockNode[]` | 按展示顺序排列的区块。每项包含唯一 `id`、`type`、`fields`，以及可选的 `style` 和预览数据 `defaultData`。 |
+
+文档结构仍处于开发阶段，不会自动迁移旧版区块字段。完整模型见[文档类型定义](./src/types/document.ts)。
+
+### 全局样式
+
+通过 `global` 传入部分设置，例如 `<EmailEditor global={{ contentWidth: 640, outerPadding: "24px" }} />`。`DEFAULT_EMAIL_GLOBAL` 导出完整默认值；`resolveEmailGlobal()` 用于补齐和归一化配置。
+
+这些设置控制邮件内容。编辑器的选中边框、工具栏等辅助界面不会进入导出的 HTML。
+
+| 参数 | 类型 / 可选值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `contentWidth` | `number` | `600` | 内容宽度，单位 px；取整并限制在 320–900。 |
+| `contentAlign` | `"left" \| "center" \| "right"` | `"center"` | 内容整体的水平位置。 |
+| `backgroundColor` | `string` | `"#ffffff"` | 邮件外层背景色。 |
+| `contentBackgroundColor` | `string` | `"#ffffff"` | 内容背景色。 |
+| `contentPadding` | `string` | `"0px"` | 内容内边距。 |
+| `outerPadding` | `string` | `"0px"` | 内容外侧留白。 |
+| `blockGap` | `string` | `"4px"` | 区块间距。 |
+| `textColor` | `string` | `"#000000"` | 默认文字颜色。 |
+| `textAlign` | `"left" \| "center" \| "right" \| "justify"` | `"left"` | 默认文字对齐。 |
+| `fontFamily` | `string` | `"Arial, Helvetica, sans-serif"` | 默认字体列表。 |
+| `fontWeight` | `"normal" \| "bold"` | `"normal"` | 默认字重。 |
+| `defaultFontSize` | `string` | `"16px"` | 默认字号。 |
+| `defaultLineHeight` | `string` | `"1.5"` | 默认行高。 |
+| `paragraphSpacing` | `string` | `"6px"` | 相邻顶层段落的间距。 |
+| `listSpacing` | `string` | `"4px"` | 列表整体（`ul` / `ol`）的上下外边距。 |
+| `listIndent` | `string` | `"22px"` | 列表缩进。 |
+| `linkColor` | `string` | `"#005bd3"` | 默认链接颜色。 |
+| `linkDecoration` | `"underline" \| "none"` | `"underline"` | 默认链接装饰。 |
+| `borderWidth` | `string` | `"0px"` | 内容边框宽度。 |
+| `borderStyle` | `"none" \| "solid" \| "dashed" \| "dotted"` | `"solid"` | 内容边框样式。 |
+| `borderColor` | `string` | `"#000000"` | 内容边框颜色。 |
+| `borderRadius` | `string` | `"0px"` | 单个圆角值，或按左上、右上、右下、左下排列的四个值。 |
+
+间距和尺寸使用 `"16px"` 等 CSS 长度字符串；内边距支持 `"12px 24px"` 等简写，行高也支持无单位数值。桌面画布和预览跟随 `contentWidth`，移动预览的视口宽度为 360px。
+
+全局间距和长度配置支持非负的 `px`、`em`、`rem`、`%` 值；除行高外，无单位长度会补为 px。不支持的值（如负长度、`calc()`、`var()`、`vh`、`vw`）会回退为对应全局参数的默认值。
+
+### 变量与模板数据
+
+```tsx
+import type { Variable } from "@standhigher/react-email-editor";
+
+export const variables: Variable[] = [
+  { name: "{{  store_name }}", description: "店铺名称", value: "示例店铺" },
+];
+```
+
+通过 `EmailEditor` 的 `variables` 参数传入此数组。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | `string` | 必填。下拉展示并原样插入的变量，保留空格，例如 `{{  store_name }}`。 |
+| `description` | `string`，可选 | 下拉选项副文案；空字符串或不传时不显示。 |
+| `value` | `string`，可选 | 预览时使用的替换文本。 |
+
+变量可以带前导点。导出模板 HTML 时，仅对与 `variables[].name` 原文精确匹配（包括空格）的 token 补齐缺失的点，并保留空格，例如 `{{  store_name }}` 变为 `{{  .store_name }}`。其他 Go template 表达式保持原样，默认不会替换为预览值。
+
+区块节点的 `defaultData: Record<string, unknown>` 可提供结构化预览数据，例如供 `{{range .products}}` 使用的数组。同名数据以区块 `defaultData` 为准，覆盖全局变量。预览解析适用于所有区块渲染出的 HTML，也包括自定义区块。HTML 区块的模板表达式直接写在 `fields.html` 中；预览渲染器支持部分 Go template 语法。
+
+### 区块配置
+
+区块节点的样式按用途分组：
+
+| 样式分组 | 用途 |
+| --- | --- |
+| `style.dimension` | 容器内边距 `padding`、外侧留白 `margin`，以及可选的 px 高度 `height`；高度包含内边距，作为最小高度。 |
+| `style.decorations` | 容器背景、边框和圆角。 |
+| `style.typography` | 区块文字样式，覆盖全局排版设置。 |
+| `style.element` | 按钮、图片和分割线等元素自身的样式，例如尺寸和对齐。 |
+
+Heading 和 Text 默认包含 `16px` 内边距。HTML 区块保留作者显式编写的内联样式。各字段见 [EmailBlockStyle](./src/types/document.ts)。
+
+通过 `blocks` 传入稳定的 `BlockDefinition[]` 添加自定义区块。必填项为 `type`、`title` 和 `render(ctx)`；可选的 `fields`、`styleFields` 配置检查器，`defaultFields`、`defaultStyle`、`defaultData` 设置新建节点的初始值。`render(ctx)` 返回 HTML 字符串，接收 `mode: "canvas" | "email"`。
+
+```tsx
+import { EmailEditor, type BlockDefinition } from "@standhigher/react-email-editor";
+
+const customBlocks: BlockDefinition[] = [{
+  type: "notice",
+  title: "Notice",
+  defaultStyle: { dimension: { padding: "16px" } },
+  render: () => '<p style="margin:0;color:#555555;">感谢订阅。</p>',
+}];
+
+export function CustomEmailPage() {
+  return <EmailEditor blocks={customBlocks} height={720} />;
+}
+```
+
+默认会为自定义区块补充通用容器间距和装饰控件。设置 `exactStyleFields: true` 后，只展示传入的样式字段；节点上已有样式仍会参与渲染。完整定义见 [BlockDefinition、FieldConfig 和 StyleFieldConfig](./src/types/block.ts)。
+
+## 读取与导出数据
+
+通过 `useRef<EmailEditorHandle>(null)` 调用以下方法：
+
+| 方法 | 返回类型 | 说明 |
+| --- | --- | --- |
+| `getData()` | `EmailEditorData` | 返回 `{ document, json, html, renderedHtml }`。 |
+| `getDocument()` | `EmailDocument` | 返回独立文档快照，可保存或用于下次编辑。 |
+| `getJson()` | `string` | 返回格式化的文档 JSON。 |
+| `getHtml()` | `string` | 返回完整邮件 HTML，保留模板表达式，仅为 `variables` 中的 token 补齐缺失的点。 |
+| `getRenderedHtml()` | `string` | 使用全局变量和区块预览数据解析模板，返回完整邮件 HTML。 |
+
+修改返回的文档快照不会改变编辑器内部状态。可使用 `onChange` 订阅文档变化。
+
+不挂载编辑器时，可调用 `documentToHtml(document, definitions?, options?)`。`definitions` 默认为 `DEFAULT_BLOCKS`，文档使用自定义区块时需包含对应定义。`options` 支持 `resolveHtmlTemplates`（默认 `false`）、`variables` 和 `templateData`。未开启解析时，仅对传入 `variables` 中的 token 补点。开启解析时，数据优先级为区块 `defaultData` 高于 `templateData`，高于 `variables`。