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

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# 更新日志
+
+## 0.2.0 — 2026-10-27
+
+### 不兼容变更
+
+- 文档格式由 `version: 1` 升为 `version: 2`，旧版本会被拒绝，不提供自动迁移。请使用 `createEmailDocument()` 创建当前版本文档；升级已有数据时，需同时调整区块字段和样式，不能只修改版本号。
+- Heading、Text、Button 的文字格式统一存于 `fields.html`；Button 不再读取 `fields.label` 和 `style.element` 中的文字样式。`EmailElementStyle` 不再继承 `EmailTypographyStyle`。
+- 内置区块按各自能力声明 `styleFields`，不再读取未启用的样式；移除内置区块的 `dimension.height` 和区块级 `typography` 配置。自定义区块仍可显式启用这些字段，`exactStyleFields` 同时约束默认样式、画布和邮件输出。
+- HTML 区块保留源码内部的段落、列表、链接和显式样式，不再注入正文排版；未声明的属性仍可继承全局样式。
+
+### 新增与改进
+
+- Button 支持画布内富文本编辑，采用单段内容，粘贴多段时以空格连接；邮件输出保留基础行内格式，并只生成一个按钮外层链接。
+- 新增 `BlockInspectorSection`、`inspectorSections`、`RichTextProfile` 和 `inlineEditProfile`，支持自定义检查器分组与富文本编辑能力；独立 `RichText` 支持 `profile`。
+- 统一颜色面板、HEX 输入和颜色重置；链接编辑改为居中弹窗，支持颜色、下划线和打开方式。
+- 优化区块操作栏、拖拽反馈、三栏布局、工具栏换行和预览高度；预览跟随文档内容展示。
+- 按钮默认填充改为黑色，按钮和图片的链接默认为空，空白链接不生成跳转；全局内容、区块、按钮和图片边框默认透明。
+- 精简中英文 README，补充 npm keywords，发布包包含中文 README 和更新日志。
+
+### 修复与验证
+
+- 修复富文本格式操作后的光标、选区和格式保留，以及列表切换时的间距和缩进保留。
+- 修复按钮导出对模板表达式中引号、比较符、注释和空格的处理。
+- 接入 Oxlint，补充区块配置、富文本、列表、按钮和颜色转换回归测试。
+
+## 0.1.0 — 2026-10-27
+
+首个正式发布版本（对应提交 `48011d9`）。
+
+- 提供 React 18 编辑器、拖拽区块、富文本编辑、检查器及桌面/移动预览。
+- 支持 JSON 文档、全局和区块样式、HTML 源码编辑、自定义区块与 Go template 预览。
+- 提供组件 ref 数据读取、独立 HTML 渲染、ESM、TypeScript 类型和独立 CSS 入口。
+- 提供 Vite playground、构建和本地 link 联调流程。
+
+## 0.0.0-stage — 2026-10-27
+
+- 发布前的包分发验证版本。

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,132 @@
-# 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 template editor with drag-and-drop blocks, inline rich text, desktop/mobile previews, JSON storage, and HTML export.
+
+## Installation
+
+Requires React 18 and React DOM 18. Includes 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 "@standhigher/react-email-editor/styles.css";
+
+const text = createBlockNode(BLOCK_TYPES.text);
+if (text) text.fields.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>
+    </>
+  );
+}
+```
+
+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. |
+| `global` | `Partial<EmailGlobalSettings>` | Overrides global styles; 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. |
+| `blocks` | `BlockDefinition[]` | Adds custom blocks; matching types replace built-in definitions. |
+| `onChange` | `(document: EmailDocument) => void` | Called on document changes, including external `global` updates that change document values. |
+| `onGlobalChange` | `(global: EmailGlobalSettings) => void` | Called for global style edits inside the editor, excluding external `global` updates. |
+
+Global style example: `global={{ contentWidth: 640, outerPadding: "24px" }}`. Defaults are exported as `DEFAULT_EMAIL_GLOBAL`.
+
+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: 2` is accepted, with no automatic migration of older documents. Create data with `createEmailDocument()` and `createBlockNode()`. See [CHANGELOG](./CHANGELOG.md) for upgrade notes.
+
+## Custom blocks
+
+Pass `BlockDefinition[]` through `blocks`. Required fields are `type`, `title`, and `render(ctx)`, which returns HTML. Use `fields` / `styleFields` for inspector controls and `defaultFields` / `defaultStyle` / `defaultData` for initial values. The render context includes `mode: "canvas" | "email"`.
+
+Built-in text formatting lives in `fields.html`, container styles in `style.dimension` / `style.decorations`, and button, image, and divider element styles in `style.element`. Rendering uses only enabled style fields. See [BlockDefinition](https://github.com/standhigher/react-email-editor/blob/main/src/types/block.ts) and [EmailDocument](https://github.com/standhigher/react-email-editor/blob/main/src/types/document.ts) for full types. When calling `documentToHtml` directly, pass the complete definition list including custom blocks as its second argument.
+
+## Local development
+
+Node.js 22.18+ and pnpm are recommended:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+Open [http://localhost:5173](http://localhost:5173). The playground loads `src/` directly; reuse an existing server. Validation:
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+node --test tests/*.test.mjs tests/*.test.ts
+```
+
+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.

package/README.zh-CN.md

@@ -0,0 +1,132 @@
+# @standhigher/react-email-editor
+
+[English](./README.md) | 简体中文
+
+React 邮件模板编辑器，支持拖拽区块、画布富文本编辑、桌面/移动预览、JSON 保存和 HTML 导出。
+
+## 安装
+
+需要 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 "@standhigher/react-email-editor/styles.css";
+
+const text = createBlockNode(BLOCK_TYPES.text);
+if (text) text.fields.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>
+    </>
+  );
+}
+```
+
+省略 `initialDocument` 即为空编辑器。Next.js App Router 中，接入组件需声明 `"use client"`，CSS 在应用允许的全局样式入口引入。使用 `height="100%"` 时，父容器需要有明确高度。
+
+## 常用参数
+
+所有 Props 均可选。
+
+| 参数 | 类型 | 行为 |
+| --- | --- | --- |
+| `initialDocument` | `EmailDocument` | 仅首次挂载读取；切换文档时通过新的 React `key` 重新挂载。 |
+| `height` | `number \| string` | 默认 `"100%"`；数字为 px。 |
+| `global` | `Partial<EmailGlobalSettings>` | 覆盖全局样式，后续更新合并到当前文档；省略字段不会恢复默认值。 |
+| `variables` | `Variable[]` | 插入和预览变量；默认 `[]`，为空时隐藏 Personalization 入口。 |
+| `blocks` | `BlockDefinition[]` | 添加自定义区块，同名 `type` 覆盖内置定义。 |
+| `onChange` | `(document: EmailDocument) => void` | 文档变化时触发，包括实际改变文档值的外部 `global` 更新。 |
+| `onGlobalChange` | `(global: EmailGlobalSettings) => void` | 编辑器内修改全局样式时触发，外部 `global` 更新不触发。 |
+
+全局样式示例：`global={{ contentWidth: 640, outerPadding: "24px" }}`。默认值通过 `DEFAULT_EMAIL_GLOBAL` 导出。
+
+内置区块：`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: 2`，不自动迁移旧文档。使用 `createEmailDocument()` 和 `createBlockNode()` 创建数据。升级差异见 [CHANGELOG](./CHANGELOG.md)。
+
+## 自定义区块
+
+通过 `blocks` 传入 `BlockDefinition[]`，必填项为 `type`、`title` 和 `render(ctx)`，返回 HTML 字符串。`fields` / `styleFields` 配置检查器，`defaultFields` / `defaultStyle` / `defaultData` 设置初始值。`render` 接收 `mode: "canvas" | "email"`。
+
+内置文字格式存于 `fields.html`，容器样式存于 `style.dimension` / `style.decorations`，按钮、图片和分割线自身样式存于 `style.element`。渲染仅使用区块启用的样式字段。完整定义见 [BlockDefinition](https://github.com/standhigher/react-email-editor/blob/main/src/types/block.ts) 和 [EmailDocument](https://github.com/standhigher/react-email-editor/blob/main/src/types/document.ts)。独立调用 `documentToHtml` 时，第二个参数需传入包含自定义区块的完整定义列表。
+
+## 本地开发
+
+建议 Node.js 22.18+，使用 pnpm：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+打开 [http://localhost:5173](http://localhost:5173)。playground 直接加载 `src/`，已有服务时复用。验证命令：
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+node --test tests/*.test.mjs tests/*.test.ts
+```
+
+本地消费方可使用 `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` 需覆盖链接目录。

package/dist/index.d.ts

@@ -0,0 +1,343 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+declare const TEXT_ALIGNS: {
+    readonly left: "left";
+    readonly center: "center";
+    readonly right: "right";
+    readonly justify: "justify";
+};
+type TextAlign = (typeof TEXT_ALIGNS)[keyof typeof TEXT_ALIGNS];
+declare const HORIZONTAL_ALIGNS: {
+    readonly left: "left";
+    readonly center: "center";
+    readonly right: "right";
+};
+type HorizontalAlign = (typeof HORIZONTAL_ALIGNS)[keyof typeof HORIZONTAL_ALIGNS];
+declare const FONT_WEIGHTS: {
+    readonly normal: "normal";
+    readonly bold: "bold";
+};
+type FontWeight = (typeof FONT_WEIGHTS)[keyof typeof FONT_WEIGHTS];
+declare const BORDER_STYLES: {
+    readonly none: "none";
+    readonly solid: "solid";
+    readonly dashed: "dashed";
+    readonly dotted: "dotted";
+};
+type BorderStyle = (typeof BORDER_STYLES)[keyof typeof BORDER_STYLES];
+declare const LINK_DECORATIONS: {
+    readonly underline: "underline";
+    readonly none: "none";
+};
+type LinkDecoration = (typeof LINK_DECORATIONS)[keyof typeof LINK_DECORATIONS];
+
+declare const DOCUMENT_VERSION: 2;
+declare const FONT_FAMILIES: readonly FieldOption[];
+declare const DEFAULT_EMAIL_GLOBAL: EmailGlobalSettings;
+
+interface EmailGlobalSettings {
+    textColor: string;
+    textAlign: TextAlign;
+    backgroundColor: string;
+    contentWidth: number;
+    contentAlign: HorizontalAlign;
+    fontFamily: string;
+    fontWeight: FontWeight;
+    contentBackgroundColor: string;
+    contentPadding: string;
+    outerPadding: string;
+    blockGap: string;
+    defaultFontSize: string;
+    defaultLineHeight: string;
+    paragraphSpacing: string;
+    listSpacing: string;
+    listIndent: string;
+    linkColor: string;
+    linkDecoration: LinkDecoration;
+    borderWidth: string;
+    borderStyle: BorderStyle;
+    borderColor: string;
+    borderRadius: string;
+}
+interface EmailDocument {
+    version: typeof DOCUMENT_VERSION;
+    subject?: string;
+    global: EmailGlobalSettings;
+    blocks: EmailBlockNode[];
+}
+interface EmailBlockNode {
+    id: string;
+    type: string;
+    fields: Record<string, unknown>;
+    style?: EmailBlockStyle;
+    defaultData?: Record<string, unknown>;
+}
+interface EmailDecorationStyle {
+    backgroundColor?: string;
+    borderRadius?: string;
+    borderWidth?: string;
+    borderColor?: string;
+    borderStyle?: BorderStyle;
+}
+interface EmailTypographyStyle {
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: FontWeight;
+    lineHeight?: string;
+    color?: string;
+    textAlign?: TextAlign;
+    paragraphSpacing?: string;
+    listSpacing?: string;
+    listIndent?: string;
+    linkColor?: string;
+    linkDecoration?: LinkDecoration;
+}
+/** 按钮、图片和分割线自身的样式，与区块容器样式独立。 */
+interface EmailElementStyle extends EmailDecorationStyle {
+    padding?: string;
+    width?: string;
+    height?: string;
+    align?: HorizontalAlign;
+}
+interface EmailSpacingStyle {
+    padding?: string;
+    margin?: string;
+    /** 自定义区块可通过 styleFields 启用；内置区块不支持。只使用 px。 */
+    height?: string;
+}
+interface EmailBlockStyle {
+    dimension?: EmailSpacingStyle;
+    /** 自定义区块可显式启用；内置区块的文字格式存于 fields.html。 */
+    typography?: EmailTypographyStyle;
+    decorations?: EmailDecorationStyle;
+    element?: EmailElementStyle;
+}
+
+type FieldType = "text" | "textarea" | "html" | "url" | "number" | "color" | "select";
+interface FieldOption {
+    label: string;
+    value: string;
+}
+interface FieldConfig {
+    type: FieldType;
+    name: string;
+    label: string;
+    defaultValue?: unknown;
+    placeholder?: string;
+    options?: FieldOption[];
+    rows?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+type StyleGroup = "general" | "dimension" | "typography" | "decorations";
+type StyleControlType = "text" | "color" | "alignment" | "select" | "number" | "range" | "spacing" | "corners";
+interface StyleFieldConfig {
+    /** e.g. "typography.fontSize" — which style slot this reads and writes */
+    id: string;
+    group: StyleGroup;
+    label: string;
+    control: StyleControlType;
+    options?: FieldOption[];
+    /** Unit suffix for a single-unit slider, e.g. "px". Omit for unitless values. */
+    unit?: string;
+    /** Email-safe units. A select appears only when more than one is listed. */
+    units?: string[];
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultValue?: string;
+    placeholder?: string;
+}
+type RenderMode = "canvas" | "email";
+interface BlockRenderContext {
+    block: EmailBlockNode;
+    fields: Record<string, unknown>;
+    style: EmailBlockStyle;
+    /** canvas/email identify the consumer; HTML template resolution is applied by the shared renderer. */
+    mode: RenderMode;
+    global: EmailGlobalSettings;
+}
+type RichTextProfile = "text" | "heading" | "button";
+/** 显式控制检查器的分组及字段归属，分组按声明顺序展示。 */
+interface BlockInspectorSection {
+    title: string;
+    fieldNames?: string[];
+    styleIds?: string[];
+    advancedStyleIds?: string[];
+}
+interface BlockDefinition {
+    type: string;
+    title: string;
+    icon?: ReactNode | string;
+    description?: string;
+    fields?: FieldConfig[];
+    styleFields?: StyleFieldConfig[];
+    inspectorSections?: BlockInspectorSection[];
+    /** 只启用 styleFields，不补容器间距和装饰；渲染也只读取启用的字段。 */
+    exactStyleFields?: boolean;
+    defaultFields?: Record<string, unknown>;
+    defaultStyle?: EmailBlockStyle;
+    /** Sample data used to render template HTML in the editor and preview. */
+    defaultData?: Record<string, unknown>;
+    /** Content is edited inline on the canvas and stored in fields.html. */
+    inlineEdit?: boolean;
+    inlineEditProfile?: RichTextProfile;
+    render: (ctx: BlockRenderContext) => string;
+}
+interface Variable {
+    /** 下拉展示并插入的变量，例如 `{{  store_name }}`。 */
+    name: string;
+    /** 下拉选项副文案。空字符串或不传时不渲染。 */
+    description?: string;
+    /** 预览时替换该变量的文本。 */
+    value?: string;
+}
+
+interface EmailEditorData {
+    document: EmailDocument;
+    json: string;
+    html: string;
+    renderedHtml: string;
+}
+interface EmailEditorHandle {
+    getData: () => EmailEditorData;
+    getDocument: () => EmailDocument;
+    getJson: () => string;
+    getHtml: () => string;
+    getRenderedHtml: () => string;
+}
+interface EmailEditorProps {
+    initialDocument?: EmailDocument;
+    /** External global settings. Incoming changes are applied to the open document. */
+    global?: Partial<EmailGlobalSettings>;
+    blocks?: BlockDefinition[];
+    variables?: Variable[];
+    height?: number | string;
+    onChange?: (document: EmailDocument) => void;
+    onGlobalChange?: (global: EmailGlobalSettings) => void;
+}
+
+declare const EmailEditor: react.ForwardRefExoticComponent<EmailEditorProps & react.RefAttributes<EmailEditorHandle>>;
+
+interface RichTextInheritedStyle {
+    fontFamily: string;
+    fontSize: string;
+    color: string;
+    fontWeight: FontWeight;
+    lineHeight: string;
+    paragraphSpacing: string;
+    listSpacing?: string;
+    listIndent?: string;
+    linkColor?: string;
+    linkDecoration?: string;
+}
+
+interface RichTextProps {
+    initialHtml: string;
+    profile?: RichTextProfile;
+    placeholder?: string;
+    variables: Variable[];
+    selected: boolean;
+    toolbarId: string;
+    toolbarCollapsed: boolean;
+    inherited?: RichTextInheritedStyle;
+    onCommit: (html: string) => void;
+    onSelect: () => void;
+}
+declare function RichText({ initialHtml, profile, placeholder, variables, selected, toolbarId, toolbarCollapsed, inherited, onCommit, onSelect, }: RichTextProps): react.JSX.Element;
+
+declare const DEFAULT_BLOCKS: BlockDefinition[];
+
+declare function resolveEmailGlobal(global?: Partial<EmailGlobalSettings> | null): EmailGlobalSettings;
+declare function createEmailDocument(blocks?: EmailBlockNode[]): EmailDocument;
+
+declare function createBlockNode(type: string, definitions?: BlockDefinition[]): EmailBlockNode | null;
+
+declare const DIMENSION_FIELDS: {
+    padding: StyleFieldConfig;
+    margin: StyleFieldConfig;
+    height: StyleFieldConfig;
+};
+declare const DECORATION_FIELDS: {
+    backgroundColor: StyleFieldConfig;
+    borderWidth: StyleFieldConfig;
+    borderStyle: StyleFieldConfig;
+    borderColor: StyleFieldConfig;
+    borderRadius: StyleFieldConfig;
+};
+declare const TYPOGRAPHY_FIELD_MAP: {
+    fontFamily: StyleFieldConfig;
+    fontSize: StyleFieldConfig;
+    fontWeight: StyleFieldConfig;
+    lineHeight: StyleFieldConfig;
+    color: StyleFieldConfig;
+    textAlign: StyleFieldConfig;
+    paragraphSpacing: StyleFieldConfig;
+    listSpacing: StyleFieldConfig;
+    listIndent: StyleFieldConfig;
+    linkColor: StyleFieldConfig;
+    linkDecoration: StyleFieldConfig;
+};
+type DimensionFieldName = keyof typeof DIMENSION_FIELDS;
+type DecorationFieldName = keyof typeof DECORATION_FIELDS;
+type TypographyFieldName = keyof typeof TYPOGRAPHY_FIELD_MAP;
+type StyleFieldOverrideMap<Name extends string> = Partial<Record<Name, Partial<StyleFieldConfig>>>;
+declare function createDimensionFields(overrides?: StyleFieldOverrideMap<DimensionFieldName>): Record<DimensionFieldName, StyleFieldConfig>;
+declare function createDecorationFields(overrides?: StyleFieldOverrideMap<DecorationFieldName>): Record<DecorationFieldName, StyleFieldConfig>;
+declare function createTypographyFields(overrides?: StyleFieldOverrideMap<TypographyFieldName>): Record<TypographyFieldName, StyleFieldConfig>;
+/** 容器字段按固定槽位合并。相同 id 使用调用方字段，其余字段按原顺序接在后面。返回值都是副本。 */
+declare function resolveBlockStyleFields(fields?: StyleFieldConfig[], exactStyleFields?: boolean): StyleFieldConfig[];
+
+interface TemplateData {
+    [key: string]: unknown;
+}
+/** Resolves template HTML for the editor and preview while leaving stored source untouched. */
+declare function renderTemplatePreview(html: string, defaultData?: TemplateData): string;
+
+interface DocumentHtmlOptions {
+    resolveHtmlTemplates?: boolean;
+    variables?: Variable[];
+    templateData?: TemplateData;
+}
+declare function documentToHtml(document: EmailDocument, definitions?: BlockDefinition[], options?: DocumentHtmlOptions): string;
+
+interface BlockRenderOptions {
+    resolveHtmlTemplate?: boolean;
+    templateData?: TemplateData;
+    variables?: Variable[];
+    global?: EmailGlobalSettings;
+}
+type BlockRenderOptionsInput = BlockRenderOptions | boolean;
+/** 用变量 name 里的字段名作为键，value 作为预览替换值。 */
+declare function variablesToTemplateData(variables: Variable[]): TemplateData;
+declare function mergeTemplateData(variables: Variable[], defaultData?: TemplateData): TemplateData | undefined;
+declare function renderBlockContent(node: EmailBlockNode, definitions?: BlockDefinition[], mode?: RenderMode, options?: BlockRenderOptionsInput): string;
+declare function renderBlock(node: EmailBlockNode, definitions?: BlockDefinition[], mode?: RenderMode, global?: EmailGlobalSettings): string;
+declare function blockToHtml(node: EmailBlockNode, definitions?: BlockDefinition[], mode?: RenderMode, options?: BlockRenderOptionsInput): string;
+
+declare function buildRenderContext(node: EmailBlockNode, mode: RenderMode, global?: EmailGlobalSettings, definition?: BlockDefinition | undefined): BlockRenderContext;
+
+declare function getBlockDefinition(type: string, definitions?: BlockDefinition[]): BlockDefinition | undefined;
+
+declare function generateId(prefix?: string): string;
+
+interface StyleGroupOption {
+    group: StyleGroup;
+    label: string;
+}
+declare const STYLE_GROUPS: StyleGroupOption[];
+
+declare const BLOCK_TYPES: {
+    readonly heading: "heading";
+    readonly text: "text";
+    readonly button: "button";
+    readonly image: "image";
+    readonly divider: "divider";
+    readonly spacer: "spacer";
+    readonly html: "html";
+};
+type BuiltinBlockType = (typeof BLOCK_TYPES)[keyof typeof BLOCK_TYPES];
+
+export { BLOCK_TYPES, BORDER_STYLES, type BlockDefinition, type BlockInspectorSection, type BlockRenderContext, type BlockRenderOptions, type BorderStyle, type BuiltinBlockType, DEFAULT_BLOCKS, DEFAULT_EMAIL_GLOBAL, DOCUMENT_VERSION, type DecorationFieldName, type DimensionFieldName, type DocumentHtmlOptions, type EmailBlockNode, type EmailBlockStyle, type EmailDecorationStyle, type EmailDocument, EmailEditor, type EmailEditorData, type EmailEditorHandle, type EmailEditorProps, type EmailElementStyle, type EmailGlobalSettings, type EmailSpacingStyle, type EmailTypographyStyle, FONT_FAMILIES, FONT_WEIGHTS, type FieldConfig, type FieldType, type FontWeight, HORIZONTAL_ALIGNS, type HorizontalAlign, LINK_DECORATIONS, type LinkDecoration, type RenderMode, RichText, type RichTextProfile, STYLE_GROUPS, type StyleControlType, type StyleFieldConfig, type StyleGroup, TEXT_ALIGNS, type TemplateData, type TextAlign, type TypographyFieldName, type Variable, blockToHtml, buildRenderContext, createBlockNode, createDecorationFields, createDimensionFields, createEmailDocument, createTypographyFields, documentToHtml, generateId, getBlockDefinition, mergeTemplateData, renderBlock, renderBlockContent, renderTemplatePreview, resolveBlockStyleFields, resolveEmailGlobal, variablesToTemplateData };