@standhigher/react-email-editor 0.2.0 → 0.4.1

package/dist/styles.css

@@ -248,6 +248,46 @@
   cursor: default;
 }
 
+.ree-switch-control {
+  width: 100%;
+  justify-content: space-between;
+  flex-direction: row-reverse;
+  font-size: 13px;
+  color: var(--ree-muted, #6d7175);
+}
+
+.ree-switch-control input {
+  display: flex;
+  align-items: center;
+  width: 32px;
+  height: 20px;
+  padding: 2px;
+  border: 0;
+  border-radius: 999px;
+  background: #b5b5b5;
+}
+
+.ree-switch-control input::before,
+.ree-switch-control input:checked::before {
+  content: "";
+  width: 16px;
+  height: 16px;
+  margin: 0;
+  border: 0;
+  border-radius: 50%;
+  background: #ffffff;
+  transform: none;
+}
+
+.ree-switch-control input:checked::before {
+  transform: translateX(12px);
+}
+
+.ree-switch-control input:focus-visible {
+  border: 2px solid #202223;
+  padding: 0;
+}
+
 .ree-range {
   -webkit-appearance: none;
   appearance: none;
@@ -375,6 +415,75 @@
   padding: calc(var(--ree-button-padding-y) - 1px) calc(var(--ree-button-padding-x) - 1px);
 }
 
+.ree-btn-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 30px;
+  height: 30px;
+  --ree-button-padding-y: 0px;
+  --ree-button-padding-x: 0px;
+  border-color: transparent;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--ree-muted);
+}
+
+.ree-btn-icon:hover {
+  border-color: transparent;
+  color: var(--ree-text);
+}
+
+.ree-btn-icon:focus-visible {
+  padding: 0;
+}
+
+.ree-btn-has-tooltip {
+  position: relative;
+}
+
+.ree-block-tooltip,
+.ree-btn-tooltip {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  z-index: 10;
+  display: none;
+  padding: 6px 9px;
+  border-radius: var(--ree-radius-sm);
+  background: var(--ree-text);
+  color: var(--ree-panel);
+  box-shadow: var(--ree-shadow-md);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.4;
+  white-space: nowrap;
+  cursor: default;
+}
+
+.ree-block-tooltip::before,
+.ree-btn-tooltip::before {
+  content: "";
+  position: absolute;
+  top: -8px;
+  left: 0;
+  width: 100%;
+  height: 8px;
+}
+
+.ree-btn-tooltip {
+  text-transform: none;
+  letter-spacing: normal;
+}
+
+.ree-block-btn:hover .ree-block-tooltip,
+.ree-block-btn:focus-visible .ree-block-tooltip,
+.ree-btn-has-tooltip:hover .ree-btn-tooltip,
+.ree-btn-has-tooltip:focus-visible .ree-btn-tooltip {
+  display: block;
+}
+
 .ree-reset {
   appearance: none;
   display: inline-flex;
@@ -534,17 +643,28 @@
   color: var(--ree-text);
 }
 
-.ree-subject-input {
+.ree-subject-field {
+  position: relative;
   flex: 1 1 360px;
-  min-width: 240px;
-  width: auto;
+  min-width: min(240px, 100%);
+}
+
+.ree-subject-input {
+  --ree-control-padding-end: 76px;
 }
 
 .ree-subject-count {
-  flex-shrink: 0;
+  position: absolute;
+  top: 0;
+  right: 12px;
+  bottom: 0;
+  display: flex;
+  align-items: center;
   color: var(--ree-muted);
   font-size: 13px;
   font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  pointer-events: none;
 }
 
 .ree-personalization {
@@ -741,6 +861,47 @@
   flex-shrink: 0;
 }
 
+.ree-library-head {
+  justify-content: space-between;
+}
+
+.ree-col-left.is-collapsed {
+  width: 52px;
+}
+
+.ree-col-left.is-collapsed .ree-library-head {
+  justify-content: center;
+  padding-left: 7px;
+  padding-right: 7px;
+}
+
+.ree-col-left:not(.is-collapsed) .ree-library-expand,
+.ree-col-left.is-collapsed .ree-library-collapse,
+.ree-col-left.is-collapsed .ree-library-label {
+  display: none;
+}
+
+@media (width < 1375px) {
+  .ree-col-left:not(.is-expanded) {
+    width: 52px;
+  }
+
+  .ree-col-left:not(.is-expanded) .ree-library-head {
+    justify-content: center;
+    padding-left: 7px;
+    padding-right: 7px;
+  }
+
+  .ree-col-left:not(.is-expanded) .ree-library-label,
+  .ree-col-left:not(.is-expanded) .ree-library-collapse {
+    display: none;
+  }
+
+  .ree-col-left:not(.is-expanded) .ree-library-expand {
+    display: inline-flex;
+  }
+}
+
 .ree-col-center {
   flex: 1;
   min-width: 0;
@@ -812,6 +973,42 @@
   font-weight: 500;
 }
 
+.ree-col-left.is-collapsed .ree-lib {
+  grid-template-columns: 1fr;
+  gap: 8px;
+  padding: 12px 7px;
+}
+
+.ree-col-left.is-collapsed .ree-lib-item {
+  justify-content: center;
+  min-height: 38px;
+  gap: 0;
+  padding: 8px;
+}
+
+.ree-col-left.is-collapsed .ree-lib-title {
+  display: none;
+}
+
+@media (width < 1375px) {
+  .ree-col-left:not(.is-expanded) .ree-lib {
+    grid-template-columns: 1fr;
+    gap: 8px;
+    padding: 12px 7px;
+  }
+
+  .ree-col-left:not(.is-expanded) .ree-lib-item {
+    justify-content: center;
+    min-height: 38px;
+    gap: 0;
+    padding: 8px;
+  }
+
+  .ree-col-left:not(.is-expanded) .ree-lib-title {
+    display: none;
+  }
+}
+
 
 /* ---------- 画布 ---------- */
 
@@ -1093,38 +1290,6 @@
   color: var(--ree-danger);
 }
 
-.ree-block-tooltip {
-  position: absolute;
-  top: calc(100% + 8px);
-  left: 0;
-  z-index: 10;
-  display: none;
-  padding: 6px 9px;
-  border-radius: var(--ree-radius-sm);
-  background: var(--ree-text);
-  color: var(--ree-panel);
-  box-shadow: var(--ree-shadow-md);
-  font-size: 12px;
-  font-weight: 500;
-  line-height: 1.4;
-  white-space: nowrap;
-  cursor: default;
-}
-
-.ree-block-tooltip::before {
-  content: "";
-  position: absolute;
-  top: -8px;
-  left: 0;
-  width: 100%;
-  height: 8px;
-}
-
-.ree-block-btn:hover .ree-block-tooltip,
-.ree-block-btn:focus-visible .ree-block-tooltip {
-  display: block;
-}
-
 .ree-block-content {
   width: 100%;
   overflow: hidden;
@@ -1650,13 +1815,13 @@
   padding-bottom: var(--ree-inspector-section-space);
 }
 
-/* Global 没有标题区，容器顶部留白会叠到第一个类目上。 */
-.ree-inspector-global {
+/* Body 没有标题区，容器顶部留白会叠到第一个类目上。 */
+.ree-inspector-body {
   padding-top: 0;
   padding-bottom: 0;
 }
 
-.ree-inspector-global > .ree-inspector-section:first-child {
+.ree-inspector-body > .ree-inspector-section:first-child {
   border-top: 0;
 }
 
@@ -1904,3 +2069,15 @@
   cursor: grabbing;
   font-weight: 500;
 }
+
+.ree-plugin-field { min-width: 0; }
+.ree-plugin-error { margin: 8px 0; padding: 8px; color: #b42318; font-size: 13px; overflow-wrap: anywhere; }
+.ree-plugin-empty { margin: 6px 0; color: #737373; font-size: 12px; }
+.ree-plugin-list { min-width: 0; margin: 0; padding: 10px; border: 1px solid #e3e3e5; border-radius: 6px; }
+.ree-plugin-list-item { display: grid; gap: 12px; padding: 12px 0; border-bottom: 1px solid #e3e3e5; }
+.ree-plugin-list-actions { display: flex; align-items: center; gap: 4px; }
+.ree-plugin-list-actions > span { margin-right: auto; }
+.ree-plugin-image { display: block; max-width: 100%; max-height: 120px; object-fit: contain; }
+.ree-plugin-richtext { min-height: 64px; padding: 8px; border: 1px solid #e3e3e5; border-radius: 4px; }
+.ree-plugin-richtext:focus-within { border-color: #000000; }
+.ree-plugin-richtext .ProseMirror { min-height: 48px; outline: none; }

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.