@standhigher/react-email-editor 0.3.0 → 0.4.3

package/dist/styles.css

@@ -693,11 +693,6 @@
   background: var(--ree-panel-secondary);
 }
 
-.ree-personalization-menu {
-  left: 0;
-  min-width: 240px;
-}
-
 .ree-subject-hint {
   flex: 0 1 auto;
   margin: 0;
@@ -1670,16 +1665,30 @@
 
 /* ---------- 变量 ---------- */
 
-.ree-var-wrap {
+.ree-input-with-variable {
   position: relative;
 }
 
-.ree-var-btn {
+.ree-input-with-variable > .ree-input {
+  --ree-control-padding-end: 48px;
+}
+
+.ree-input-with-variable > .ree-textarea {
+  display: block;
+}
+
+.ree-personalization-suffix {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+}
+
+.ree-personalization-suffix-btn {
   appearance: none;
   border: none;
   background: transparent;
   min-width: 30px;
-  height: 24px;
+  height: 26px;
   padding: 0 6px;
   border-radius: var(--ree-radius-sm);
   cursor: pointer;
@@ -1687,10 +1696,16 @@
   font-size: 12px;
 }
 
-.ree-var-btn:hover {
+.ree-personalization-suffix-btn:hover {
   background: var(--ree-panel-secondary);
 }
 
+.ree-personalization-suffix-btn:focus-visible,
+.ree-personalization-btn:focus-visible {
+  outline: 2px solid var(--ree-text);
+  outline-offset: -2px;
+}
+
 .ree-var-menu {
   position: absolute;
   top: 100%;
@@ -1707,6 +1722,16 @@
   color: var(--ree-text, #202223);
 }
 
+.ree-var-menu.ree-personalization-menu {
+  position: fixed;
+  inset: auto;
+  margin: 0;
+  z-index: 1000;
+  width: 240px;
+  min-width: 0;
+  max-width: calc(100vw - 16px);
+}
+
 .ree-var-item {
   display: flex;
   flex-direction: column;
@@ -1730,6 +1755,13 @@
   color: var(--ree-primary);
 }
 
+.ree-var-name,
+.ree-var-label {
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}
+
 .ree-var-label {
   font-size: 12px;
   color: var(--ree-muted);
@@ -1862,28 +1894,6 @@
   margin-bottom: 14px;
 }
 
-.ree-field-label:has(> .ree-var-wrap) {
-  position: relative;
-  justify-content: flex-start;
-}
-
-.ree-field-label > .ree-var-wrap {
-  position: static;
-}
-
-.ree-field-label .ree-var-menu {
-  left: 0;
-  width: min(280px, 100%);
-  min-width: 0;
-}
-
-.ree-field-label .ree-var-name,
-.ree-field-label .ree-var-label {
-  max-width: 100%;
-  overflow-wrap: anywhere;
-  white-space: pre-wrap;
-}
-
 /* ---------- 配置控件 ---------- */
 
 .ree-textarea {

package/docs/advanced-examples.md

@@ -0,0 +1,265 @@
+# Advanced examples
+
+[简体中文](./advanced-examples.zh-CN.md) | [API reference](./api.md) | [Basic examples](./basic-examples.md)
+
+Save each named code block in its own file and import package CSS once. Business requests are injected through props; these examples assume no backend routes.
+
+## 1. Validate before async saving
+
+Validation can expose control issues early; export still needs to catch plugin rendering errors. Implement saveDocument(data) in your app, returning a Promise. Failures remain retryable.
+
+```tsx
+// ValidatedEditor.tsx
+import { useState } from "react";
+import {
+  EmailEditor, useEmailEditor, type EmailEditorData,
+} from "@standhigher/react-email-editor";
+
+interface ValidatedEditorProps {
+  saveDocument: (data: EmailEditorData) => Promise<void>;
+}
+
+export function ValidatedEditor({ saveDocument }: ValidatedEditorProps) {
+  const editor = useEmailEditor();
+  const [status, setStatus] = useState("Not saved yet");
+  const [saving, setSaving] = useState(false);
+
+  async function save() {
+    setSaving(true);
+    try {
+      const issues = editor.validate();
+      if (issues.length) {
+        setStatus(issues.map((issue) => `${issue.controlPath}: ${issue.message}`).join("; "));
+        return;
+      }
+      const data = editor.getData();
+      await saveDocument(data);
+      setStatus("Snapshot saved; edits made during saving need another save");
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : "Save failed; retry");
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" disabled={saving} onClick={save}>{saving ? "Saving…" : "Save / retry"}</button>
+      <output aria-live="polite">{status}</output>
+    </>
+  );
+}
+```
+
+getData() generates both template and preview HTML. For JSON-only drafts use getDocument(), which avoids blocking persistence on invalid controls or rendering failures. Editing remains enabled during saving; the result corresponds to the detached snapshot taken on click.
+
+## 2. Share configuration between isolated instances and subscribe locally
+
+```tsx
+// DocumentSummary.tsx
+import { useEmailEditorState, type EmailEditorInstance } from "@standhigher/react-email-editor";
+
+interface DocumentSummaryProps {
+  editor: EmailEditorInstance;
+}
+
+export function DocumentSummary({ editor }: DocumentSummaryProps) {
+  const { document } = useEmailEditorState(editor);
+  return <output>{document.blocks.length} blocks</output>;
+}
+```
+
+```tsx
+// ComparisonEditors.tsx
+import { EmailEditor, useEmailEditor, useEmailEditorConfig } from "@standhigher/react-email-editor";
+import { DocumentSummary } from "./DocumentSummary";
+
+const builtins = ["heading", "text", "button", "image"];
+
+export function ComparisonEditors() {
+  const config = useEmailEditorConfig({ builtins });
+  const left = useEmailEditor({ config, body: { contentWidth: 640 } });
+  const right = useEmailEditor({ config, body: { contentWidth: 480 } });
+  return (
+    <>
+      <DocumentSummary editor={left} /><EmailEditor editor={left} height={600} />
+      <DocumentSummary editor={right} /><EmailEditor editor={right} height={600} />
+    </>
+  );
+}
+```
+
+Documents, selection and reset are isolated. Only summary components subscribe to document changes. Shared configuration describes block capabilities without sharing mutable documents.
+
+## 3. Business block with multiple rich-text regions and a list
+
+This recommendation block combines two rich-text regions and a product list. Controls are the source of truth for types and defaults. Canvas defines editing UI; renderEmail defines email HTML.
+
+```ts
+// recommendation-controls.ts
+import { EmailControls, type ControlValues } from "@standhigher/react-email-editor";
+
+export const recommendationControls = {
+  intro: EmailControls.richText({ label: "Introduction", defaultValue: "<p>This week's picks</p>" }),
+  footer: EmailControls.richText({ label: "Footer", defaultValue: "<p>Thanks for subscribing</p>" }),
+  products: EmailControls.list({
+    label: "Products", min: 1, max: 8,
+    controls: {
+      name: EmailControls.text({ label: "Name", validate: (value) => value.trim() ? undefined : "Enter a name" }),
+      image: EmailControls.image({ label: "Image" }),
+      url: EmailControls.url({ label: "Link" }),
+    },
+    defaultValue: [{ name: "Example product", image: "", url: "https://example.com/product" }],
+  }),
+};
+export type RecommendationValues = ControlValues<typeof recommendationControls>;
+```
+
+```tsx
+// RecommendationCanvas.tsx
+import { EditableRichText, type PluginEditorProps } from "@standhigher/react-email-editor";
+import type { RecommendationValues } from "./recommendation-controls";
+
+export function RecommendationCanvas({ controls }: PluginEditorProps<RecommendationValues>) {
+  return (
+    <div>
+      <EditableRichText control="intro" />
+      <ul>{controls.products.map((product, index) => <li key={index}>{product.name}</li>)}</ul>
+      <EditableRichText control="footer" />
+    </div>
+  );
+}
+```
+
+```tsx
+// RecommendationInspector.tsx
+import { ControlEditor } from "@standhigher/react-email-editor";
+
+export function RecommendationInspector() {
+  return <ControlEditor control="products" />;
+}
+```
+
+```ts
+// recommendation.ts
+import { defineBlock } from "@standhigher/react-email-editor";
+import { recommendationControls } from "./recommendation-controls";
+import { RecommendationCanvas } from "./RecommendationCanvas";
+import { RecommendationInspector } from "./RecommendationInspector";
+
+export const recommendation = defineBlock({
+  type: "shop.recommendation",
+  title: "Recommendations",
+  controls: recommendationControls,
+  Canvas: RecommendationCanvas,
+  Inspector: RecommendationInspector,
+  defaultStyle: { dimension: { padding: "16px" } },
+  renderEmail: ({ controls, email }) => email.html`
+    ${email.richText(controls.intro)}
+    ${controls.products.map((product) => email.html`
+      <p><strong>${product.name}</strong></p>
+      ${product.image ? email.image({ src: product.image, alt: product.name }) : email.raw("")}
+      ${email.button({ href: product.url, label: "View product" })}
+    `)}
+    ${email.richText(controls.footer)}
+  `,
+});
+```
+
+```tsx
+// RecommendationEditor.tsx
+import { useMemo, useState } from "react";
+import {
+  createEmailDocument, EmailEditor, useEmailEditor, useEmailEditorConfig,
+} from "@standhigher/react-email-editor";
+import { recommendation } from "./recommendation";
+
+const plugins = [recommendation];
+
+export function RecommendationEditor() {
+  const config = useEmailEditorConfig({ plugins });
+  const initialDocument = useMemo(
+    () => createEmailDocument([config.createBlock(recommendation.type)]),
+    [config],
+  );
+  const editor = useEmailEditor({ config, initialDocument });
+  const [html, setHtml] = useState("");
+  const [error, setError] = useState("");
+
+  function exportHtml() {
+    try {
+      // The same configuration works for export without mounting the UI.
+      setHtml(config.toHtml(editor.getDocument()));
+      setError("");
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : "Export failed");
+    }
+  }
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" onClick={exportHtml}>Export</button>
+      {error ? <p role="alert">{error}</p> : null}
+      <pre>{html}</pre>
+    </>
+  );
+}
+```
+
+config.toHtml() and the editor share the same registry; loading saved JSON requires the plugin again. ControlEditor provides list additions, deletions and child editing; Canvas only displays product names. Business pickers can use PluginEditorProps.setControls(patch) to fill related values in one update; submit a complete array for nested lists.
+
+## 4. Integrate an existing image resource picker
+
+```tsx
+// ResourceEditor.tsx
+import { useCallback } from "react";
+import {
+  EmailEditor, useEmailEditor, useEmailEditorConfig, type ImagePickerContext,
+} from "@standhigher/react-email-editor";
+
+interface ResourceEditorProps {
+  openLibrary: (request: { currentUrl: string; signal: AbortSignal }) => Promise<string | null>;
+}
+
+export function ResourceEditor({ openLibrary }: ResourceEditorProps) {
+  const pickImage = useCallback(
+    ({ value, signal }: ImagePickerContext) => openLibrary({ currentUrl: value, signal }),
+    [openLibrary],
+  );
+  const config = useEmailEditorConfig({ pickImage });
+  const editor = useEmailEditor({ config });
+  return <EmailEditor editor={editor} height={720} />;
+}
+```
+
+Your resource library implements its dialog, search, empty results, uploads and cancellation. Pass signal to requests. Return an allowed URL, null to cancel, or throw to show retry. The editor provides loading/error/retry for image requests, ignores stale results and cancels on unmount.
+
+## 5. Structured template data and single-block preview
+
+```ts
+// template-preview.ts
+import {
+  BLOCK_TYPES, blockToHtml, createBlockNode, createEmailDocument, documentToHtml,
+  mergeTemplateData, type Variable,
+} 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}}</p>
+  {{range .products}}<p>{{.name}}</p>{{end}}`;
+const variables: Variable[] = [{ name: "{{.customer}}", value: "Sam" }];
+const templateData = { products: [{ name: "Tea" }, { name: "Coffee" }] };
+const document = createEmailDocument([block]);
+
+export const template = documentToHtml(document, undefined, { variables });
+export const preview = documentToHtml(document, undefined, {
+  variables, templateData, resolveHtmlTemplates: true,
+});
+export const fragment = blockToHtml(block, undefined, "email", {
+  resolveHtmlTemplate: true,
+  templateData: mergeTemplateData(variables, { ...templateData, ...block.defaultData }),
+});
+```
+
+Complete documents shallow-merge variables → templateData → block.defaultData, with later data winning. Single-block rendering does not merge variables automatically; this example merges explicitly and uses the singular resolveHtmlTemplate option. Your application chooses the actual sending engine; preview only supports a subset of Go templates.

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

@@ -0,0 +1,265 @@
+# 复杂场景示例
+
+[English](./advanced-examples.md) | [API 参考](./api.zh-CN.md) | [基础场景](./basic-examples.zh-CN.md)
+
+每段标注文件名的代码保存为独立文件；引入一次包样式。业务请求通过 Props 注入，示例不会假设你的后端路径。
+
+## 1. 校验后异步保存
+
+校验可提前展示控件错误，导出仍需捕获插件渲染异常。调用方实现 `saveDocument(data)`，返回保存完成的 Promise；失败会显示可重试状态。
+
+```tsx
+// ValidatedEditor.tsx
+import { useState } from "react";
+import {
+  EmailEditor, useEmailEditor, type EmailEditorData,
+} from "@standhigher/react-email-editor";
+
+interface ValidatedEditorProps {
+  saveDocument: (data: EmailEditorData) => Promise<void>;
+}
+
+export function ValidatedEditor({ saveDocument }: ValidatedEditorProps) {
+  const editor = useEmailEditor();
+  const [status, setStatus] = useState("尚未保存");
+  const [saving, setSaving] = useState(false);
+
+  async function save() {
+    setSaving(true);
+    try {
+      const issues = editor.validate();
+      if (issues.length) {
+        setStatus(issues.map((issue) => `${issue.controlPath}: ${issue.message}`).join("；"));
+        return;
+      }
+      const data = editor.getData();
+      await saveDocument(data);
+      setStatus("本次快照已保存；保存期间的后续编辑需再次保存");
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : "保存失败，请重试");
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" disabled={saving} onClick={save}>{saving ? "保存中…" : "保存 / 重试"}</button>
+      <output aria-live="polite">{status}</output>
+    </>
+  );
+}
+```
+
+`getData()` 同时生成模板与预览 HTML；只需要草稿 JSON 时使用 `getDocument()`，不会因无效控件或模板渲染阻止草稿持久化。保存期间编辑器仍可编辑，保存结果对应点击时的独立快照。
+
+## 2. 多实例共享配置，局部订阅文档
+
+```tsx
+// DocumentSummary.tsx
+import { useEmailEditorState, type EmailEditorInstance } from "@standhigher/react-email-editor";
+
+interface DocumentSummaryProps {
+  editor: EmailEditorInstance;
+}
+
+export function DocumentSummary({ editor }: DocumentSummaryProps) {
+  const { document } = useEmailEditorState(editor);
+  return <output>{document.blocks.length} 个区块</output>;
+}
+```
+
+```tsx
+// ComparisonEditors.tsx
+import { EmailEditor, useEmailEditor, useEmailEditorConfig } from "@standhigher/react-email-editor";
+import { DocumentSummary } from "./DocumentSummary";
+
+const builtins = ["heading", "text", "button", "image"];
+
+export function ComparisonEditors() {
+  const config = useEmailEditorConfig({ builtins });
+  const left = useEmailEditor({ config, body: { contentWidth: 640 } });
+  const right = useEmailEditor({ config, body: { contentWidth: 480 } });
+  return (
+    <>
+      <DocumentSummary editor={left} /><EmailEditor editor={left} height={600} />
+      <DocumentSummary editor={right} /><EmailEditor editor={right} height={600} />
+    </>
+  );
+}
+```
+
+两个实例的文档、选择、重置互相独立。仅摘要组件订阅文档变化。共享配置定义区块能力，不共享可变文档。
+
+## 3. 业务区块、多区域富文本与列表
+
+以下商品推荐区块同时包含两个富文本编辑区和一个商品列表。控件声明是类型和默认值的唯一来源；Canvas 负责编辑布局，`renderEmail` 负责邮件 HTML。
+
+```ts
+// recommendation-controls.ts
+import { EmailControls, type ControlValues } from "@standhigher/react-email-editor";
+
+export const recommendationControls = {
+  intro: EmailControls.richText({ label: "介绍", defaultValue: "<p>本周推荐</p>" }),
+  footer: EmailControls.richText({ label: "结语", defaultValue: "<p>谢谢订阅</p>" }),
+  products: EmailControls.list({
+    label: "商品", min: 1, max: 8,
+    controls: {
+      name: EmailControls.text({ label: "名称", validate: (value) => value.trim() ? undefined : "请填写名称" }),
+      image: EmailControls.image({ label: "图片" }),
+      url: EmailControls.url({ label: "链接" }),
+    },
+    defaultValue: [{ name: "示例商品", image: "", url: "https://example.com/product" }],
+  }),
+};
+export type RecommendationValues = ControlValues<typeof recommendationControls>;
+```
+
+```tsx
+// RecommendationCanvas.tsx
+import { EditableRichText, type PluginEditorProps } from "@standhigher/react-email-editor";
+import type { RecommendationValues } from "./recommendation-controls";
+
+export function RecommendationCanvas({ controls }: PluginEditorProps<RecommendationValues>) {
+  return (
+    <div>
+      <EditableRichText control="intro" />
+      <ul>{controls.products.map((product, index) => <li key={index}>{product.name}</li>)}</ul>
+      <EditableRichText control="footer" />
+    </div>
+  );
+}
+```
+
+```tsx
+// RecommendationInspector.tsx
+import { ControlEditor } from "@standhigher/react-email-editor";
+
+export function RecommendationInspector() {
+  return <ControlEditor control="products" />;
+}
+```
+
+```ts
+// recommendation.ts
+import { defineBlock } from "@standhigher/react-email-editor";
+import { recommendationControls } from "./recommendation-controls";
+import { RecommendationCanvas } from "./RecommendationCanvas";
+import { RecommendationInspector } from "./RecommendationInspector";
+
+export const recommendation = defineBlock({
+  type: "shop.recommendation",
+  title: "商品推荐",
+  controls: recommendationControls,
+  Canvas: RecommendationCanvas,
+  Inspector: RecommendationInspector,
+  defaultStyle: { dimension: { padding: "16px" } },
+  renderEmail: ({ controls, email }) => email.html`
+    ${email.richText(controls.intro)}
+    ${controls.products.map((product) => email.html`
+      <p><strong>${product.name}</strong></p>
+      ${product.image ? email.image({ src: product.image, alt: product.name }) : email.raw("")}
+      ${email.button({ href: product.url, label: "查看商品" })}
+    `)}
+    ${email.richText(controls.footer)}
+  `,
+});
+```
+
+```tsx
+// RecommendationEditor.tsx
+import { useMemo, useState } from "react";
+import {
+  createEmailDocument, EmailEditor, useEmailEditor, useEmailEditorConfig,
+} from "@standhigher/react-email-editor";
+import { recommendation } from "./recommendation";
+
+const plugins = [recommendation];
+
+export function RecommendationEditor() {
+  const config = useEmailEditorConfig({ plugins });
+  const initialDocument = useMemo(
+    () => createEmailDocument([config.createBlock(recommendation.type)]),
+    [config],
+  );
+  const editor = useEmailEditor({ config, initialDocument });
+  const [html, setHtml] = useState("");
+  const [error, setError] = useState("");
+
+  function exportHtml() {
+    try {
+      // 同一配置也可供不挂载 UI 的导出流程使用。
+      setHtml(config.toHtml(editor.getDocument()));
+      setError("");
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : "导出失败");
+    }
+  }
+  return (
+    <>
+      <EmailEditor editor={editor} height={720} />
+      <button type="button" onClick={exportHtml}>导出</button>
+      {error ? <p role="alert">{error}</p> : null}
+      <pre>{html}</pre>
+    </>
+  );
+}
+```
+
+`config.toHtml()` 和编辑器共用同一注册表，保存 JSON 后再加载也必须注册该插件。列表编辑由 `ControlEditor` 提供增加、删除及子控件编辑；Canvas 的列表只展示商品名称。业务选择器一次填充多个关联字段可使用 `PluginEditorProps.setControls(patch)`，嵌套列表提交完整数组。
+
+## 4. 接入已有图片资源选择器
+
+```tsx
+// ResourceEditor.tsx
+import { useCallback } from "react";
+import {
+  EmailEditor, useEmailEditor, useEmailEditorConfig, type ImagePickerContext,
+} from "@standhigher/react-email-editor";
+
+interface ResourceEditorProps {
+  openLibrary: (request: { currentUrl: string; signal: AbortSignal }) => Promise<string | null>;
+}
+
+export function ResourceEditor({ openLibrary }: ResourceEditorProps) {
+  const pickImage = useCallback(
+    ({ value, signal }: ImagePickerContext) => openLibrary({ currentUrl: value, signal }),
+    [openLibrary],
+  );
+  const config = useEmailEditorConfig({ pickImage });
+  const editor = useEmailEditor({ config });
+  return <EmailEditor editor={editor} height={720} />;
+}
+```
+
+调用方的资源库应处理弹窗、搜索、空结果、上传与取消；传入 signal 给网络请求。返回允许协议的地址，返回 null 表示取消，抛错由编辑器显示重试。编辑器对图片请求提供 loading/error/retry，忽略过期结果，卸载时取消请求。
+
+## 5. 批量模板数据与单区块预览
+
+```ts
+// template-preview.ts
+import {
+  BLOCK_TYPES, blockToHtml, createBlockNode, createEmailDocument, documentToHtml,
+  mergeTemplateData, type Variable,
+} from "@standhigher/react-email-editor";
+
+const block = createBlockNode(BLOCK_TYPES.html);
+if (!block) throw new Error("HTML 区块未注册");
+block.controls.html = `<p>你好，{{.customer}}</p>
+  {{range .products}}<p>{{.name}}</p>{{end}}`;
+const variables: Variable[] = [{ name: "{{.customer}}", value: "李小明" }];
+const templateData = { products: [{ name: "茶叶" }, { name: "咖啡" }] };
+const document = createEmailDocument([block]);
+
+export const template = documentToHtml(document, undefined, { variables });
+export const preview = documentToHtml(document, undefined, {
+  variables, templateData, resolveHtmlTemplates: true,
+});
+export const fragment = blockToHtml(block, undefined, "email", {
+  resolveHtmlTemplate: true,
+  templateData: mergeTemplateData(variables, { ...templateData, ...block.defaultData }),
+});
+```
+
+完整文档自动按顶层浅合并 `variables → templateData → block.defaultData`，后者优先。单区块不会自动合并变量；示例显式合并，并使用单数 `resolveHtmlTemplate`。真实发送端的模板引擎由应用决定，预览仅支持部分 Go template 语法。