@standhigher/react-email-editor 0.3.0 → 0.4.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)。

package/docs/release.md

@@ -0,0 +1,38 @@
+# npm release guide
+
+English | [简体中文](./release.zh-CN.md)
+
+## Toolchain and package configuration
+
+Development uses Node 24 LTS (`.nvmrc`) and pnpm 10.16.1 (`packageManager`). The complete test suite needs Node 22.18+. These development requirements are not consumer requirements, so the package does not declare `engines`. React / React DOM 18 remain the supported peers; React 19 requires a separate compatibility validation.
+
+The manifest declares MIT licensing, repository, homepage, issue tracker and the public npm registry. `sideEffects: ["**/*.css"]` preserves CSS imports while allowing unused JavaScript modules to be removed. Actual tree shaking depends on module contents and the consumer's bundler.
+
+The package includes built assets, Markdown documentation and SVGs under `docs/` (including [English](./changelog.md) and [Chinese](./changelog.zh-CN.md) changelogs), plus both READMEs. npm automatically includes `package.json` and `LICENSE`. Source, playground, tests, caches and PNG originals are excluded.
+
+## README images
+
+Both READMEs use absolute CDN URLs pinned to the publicly published `0.4.1` package, which contains the English and Chinese PNG and SVG assets. This avoids relative-path resolution on npm, GitHub branch synchronization and shipping PNG copies in every release.
+
+When updating a diagram, host the new image at a stable public URL before changing either README. Do not reference an unpublished version or a `latest` URL that may no longer contain PNGs. Verify an unauthenticated `200` response and the correct image Content-Type.
+
+README language switches, documentation, changelog and section links use absolute GitHub `blob/main` URLs. Push the corresponding commit before publishing so the linked READMEs, `docs/` and changelog exist on GitHub; local-only files still return 404. Relative links inside documentation pages are resolved by GitHub against their directories.
+
+## Local checks and publishing
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+npm pack --dry-run
+```
+
+`pnpm check` runs type checking, linting, build and Node tests in order. Tests cover package contents, README image URLs and consumer CSS preservation. `pnpm test` requires an existing build. `prepack` builds assets; `prepublishOnly` runs the complete check before local publishing.
+
+To publish locally, first update both changelogs and select an unpublished version:
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm publish
+```
+
+The npm account needs permission for the `@standhigher` scope and any required 2FA. Published versions cannot be overwritten. Committing or pushing code does not automatically publish a package.

package/docs/release.zh-CN.md

@@ -0,0 +1,38 @@
+# npm 发布指南
+
+[English](./release.md) | 简体中文
+
+## 工具链与包配置
+
+开发默认使用 Node 24 LTS（`.nvmrc`）和 pnpm 10.16.1（`packageManager`）。完整测试最低需要 Node 22.18；这不是消费方安装要求，因此包没有添加 `engines` 限制。当前仍只声明 React 18 / React DOM 18 支持，React 19 需完成独立兼容性验证后再扩大 peer 范围。
+
+`package.json` 声明 MIT 许可证、仓库、主页、Issue 地址及公开 npm registry。`sideEffects: ["**/*.css"]` 保留消费方的 CSS 导入，允许 bundler 丢弃未使用的 JavaScript 模块；实际裁剪效果取决于模块内容和消费方 bundler。
+
+`files` 只发布构建产物、`docs/` 下的 Markdown 文档和 SVG（含[英文](./changelog.md)与[中文](./changelog.zh-CN.md)更新日志），以及中英文 README；npm 自动包含 `package.json` 和 `LICENSE`。源码、playground、测试、本地缓存和 PNG 原图不进入包。
+
+## README 图片
+
+npm README 使用固定版本的绝对 CDN 地址，图片来自已公开发布的 `0.4.1` 包。中英文 PNG 和 SVG 源文件均由该版本提供，不依赖本地相对路径或 GitHub 分支同步，也不需要在每个新版包中重复分发 PNG。
+
+更新架构图时，先将新图片放到可公开读取的稳定地址，再更新两个 README 的图片与查看链接。不要把地址替换成尚未发布的版本，也不要使用会随 `latest` 变化且可能缺失 PNG 的路径。图片地址应无需登录，返回 `200` 和正确的图片 Content-Type。
+
+README 的语言切换、文档、更新日志和章节导航使用 GitHub `blob/main` 绝对地址。发布前须先推送相应提交，确保 GitHub 上的 README、`docs/` 与更新日志均已同步；仅在本地存在的文档仍会返回 404。文档页内部的相对链接继续由 GitHub 按目录解析。
+
+## 本地检查与发布
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+npm pack --dry-run
+```
+
+`pnpm check` 顺序执行类型检查、lint、构建和 Node 测试；测试包含发布文件范围、README 图片地址及消费方 CSS 保留验证。`pnpm test` 只执行测试，需先构建。`prepack` 负责构建；本地 `npm publish` 的 `prepublishOnly` 会执行完整校验。
+
+需要本地手动发布时，在确认版本未发布、中英文更新日志已同步后执行：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm publish
+```
+
+发布需要 npm 账号对 `@standhigher` scope 的权限及账号要求的 2FA。已发布的相同版本不能覆盖。代码提交或推送不会自动发布 npm 包。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standhigher/react-email-editor",
-  "version": "0.3.0",
+  "version": "0.4.3",
   "type": "module",
   "description": "React email template editor with drag-and-drop blocks, rich text, JSON storage, and HTML export.",
   "keywords": [
@@ -17,6 +17,16 @@
     "go-template"
   ],
   "author": "Nono",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/standhigher/react-email-editor.git"
+  },
+  "homepage": "https://github.com/standhigher/react-email-editor#readme",
+  "bugs": {
+    "url": "https://github.com/standhigher/react-email-editor/issues"
+  },
+  "packageManager": "pnpm@10.16.1",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -27,21 +37,26 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": ["**/*.css"],
   "files": [
     "dist",
-    "docs",
+    "docs/**/*.md",
+    "docs/**/*.svg",
     "README.md",
-    "README.zh-CN.md",
-    "CHANGELOG.md"
+    "README.zh-CN.md"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
     "dev": "vite --config playground/vite.config.ts",
     "build": "tsup",
     "build:watch": "tsup --watch src",
+    "test": "node --test tests/*.test.mjs tests/*.test.ts",
+    "check": "pnpm typecheck && pnpm lint && pnpm build && pnpm test",
     "prepack": "pnpm build",
+    "prepublishOnly": "pnpm check",
     "typecheck": "tsc --noEmit && tsc --noEmit -p playground",
     "lint": "oxlint . --deny-warnings --report-unused-disable-directives",
     "lint:fix": "pnpm lint --fix"