@standhigher/react-email-editor 0.4.3 → 0.5.2

package/README.md

@@ -15,7 +15,7 @@ Drag content onto a canvas, style your email, preview it, then save editable JSO
 Requires React 18 and React DOM 18. Ships ESM and TypeScript declarations.
 
 ```bash
-pnpm add @standhigher/react-email-editor
+npm install @standhigher/react-email-editor
 ```
 
 ```tsx
@@ -28,15 +28,13 @@ export function EmailPage() {
 }
 ```
 
-With Next.js App Router, add `"use client"` to the integration component and import CSS from an allowed global stylesheet entry. Your app implements persistence, resource uploads and email delivery.
-
 ## Run locally
 
-Use Node.js 24 LTS (`.nvmrc`; at least 22.18 for the complete test suite) and pnpm 10.16.1 (`packageManager`):
+Use Node.js 24 LTS (`.nvmrc`; at least 22.18 for the complete test suite):
 
 ```bash
-pnpm install --frozen-lockfile
-pnpm dev
+npm install
+npm run dev
 ```
 
 Open [http://localhost:5173](http://localhost:5173); reuse an existing server when available. See [development and local linking](https://github.com/standhigher/react-email-editor/blob/main/docs/api.md#development-and-local-linking) for build and validation commands.
@@ -45,9 +43,8 @@ Open [http://localhost:5173](http://localhost:5173); reuse an existing server wh
 
 - [API reference](https://github.com/standhigher/react-email-editor/blob/main/docs/api.md): every public export, parameter, default and type.
 - [Basic examples](https://github.com/standhigher/react-email-editor/blob/main/docs/basic-examples.md): initial content, saving/loading, body styles, variables and preview.
+- [Template preview and custom engines](https://github.com/standhigher/react-email-editor/blob/main/docs/template-engines.md).
 - [Advanced examples](https://github.com/standhigher/react-email-editor/blob/main/docs/advanced-examples.md): validated saving, multiple instances, custom blocks, multiple editing regions, resource adapters and standalone export.
 - [Custom block guide](https://github.com/standhigher/react-email-editor/blob/main/docs/custom-blocks.md): detailed controls, plugins and rendering helpers.
 - [Release guide](https://github.com/standhigher/react-email-editor/blob/main/docs/release.md): package checks and manual npm publishing.
 - [Changelog](https://github.com/standhigher/react-email-editor/blob/main/docs/changelog.md).
-
-The document format is under development. Only `version: 4` is supported, without automatic migration of older documents.

package/README.zh-CN.md

@@ -15,7 +15,7 @@
 需要 React 18 和 React DOM 18；包提供 ESM 和 TypeScript 类型。
 
 ```bash
-pnpm add @standhigher/react-email-editor
+npm install @standhigher/react-email-editor
 ```
 
 ```tsx
@@ -28,15 +28,13 @@ export function EmailPage() {
 }
 ```
 
-Next.js App Router 的接入组件需声明 `"use client"`；样式在应用允许的全局样式入口引入。保存、上传资源与发送邮件由你的应用实现。
-
 ## 本地启动
 
-推荐 Node.js 24 LTS（`.nvmrc`；完整测试最低需要 22.18）和 pnpm 10.16.1（`packageManager`）：
+推荐 Node.js 24 LTS（`.nvmrc`；完整测试最低需要 22.18）：
 
 ```bash
-pnpm install --frozen-lockfile
-pnpm dev
+npm install
+npm run dev
 ```
 
 打开 [http://localhost:5173](http://localhost:5173)，已有服务时优先复用。构建与校验命令见 [API 文档的开发说明](https://github.com/standhigher/react-email-editor/blob/main/docs/api.zh-CN.md#开发与本地联调)。
@@ -45,9 +43,8 @@ pnpm dev
 
 - [API 参考](https://github.com/standhigher/react-email-editor/blob/main/docs/api.zh-CN.md)：所有公共导出、参数、默认值与类型。
 - [基础场景](https://github.com/standhigher/react-email-editor/blob/main/docs/basic-examples.zh-CN.md)：初始内容、保存恢复、主体样式、变量及预览。
+- [模板预览与自定义引擎](https://github.com/standhigher/react-email-editor/blob/main/docs/template-engines.zh-CN.md)。
 - [复杂场景](https://github.com/standhigher/react-email-editor/blob/main/docs/advanced-examples.zh-CN.md)：校验后保存、多实例、自定义区块、多区域编辑、资源适配与独立导出。
 - [自定义区块指南](https://github.com/standhigher/react-email-editor/blob/main/docs/custom-blocks.zh-CN.md)：控件、插件和渲染工具的完整说明。
 - [发布指南](https://github.com/standhigher/react-email-editor/blob/main/docs/release.zh-CN.md)：发布包校验与本地手动发布。
 - [更新记录](https://github.com/standhigher/react-email-editor/blob/main/docs/changelog.zh-CN.md)。
-
-文档格式仍处于开发阶段，当前只支持 `version: 4`，不自动迁移旧版文档。

package/dist/index.d.ts

@@ -37,10 +37,6 @@ declare const LINK_DECORATIONS: {
 /** Link decoration: underline or none. */
 type LinkDecoration = (typeof LINK_DECORATIONS)[keyof typeof LINK_DECORATIONS];
 
-declare const DOCUMENT_VERSION: 4;
-declare const FONT_FAMILIES: readonly ControlOption[];
-declare const DEFAULT_EMAIL_BODY: EmailBodySettings;
-
 /** Email body layout and inherited defaults. */
 interface EmailBodySettings {
     /** Default text color. */
@@ -49,7 +45,7 @@ interface EmailBodySettings {
     backgroundColor: string;
     /** Maximum content width in px, normalized to an integer from 320 to 900. */
     contentWidth: number;
-    /** Default CSS font stack. */
+    /** CSS font stack; empty uses the internal default Arial, Helvetica, sans-serif. */
     fontFamily: string;
     /** Default font weight: normal or bold. */
     fontWeight: FontWeight;
@@ -68,10 +64,10 @@ interface EmailBodySettings {
     /** Content border color. */
     borderColor: string;
 }
-/** Persistable email document; only v4 is supported. */
+/** Persistable email document, accepted according to its structure. */
 interface EmailDocument {
-    /** Format version; must be DOCUMENT_VERSION (4). */
-    version: typeof DOCUMENT_VERSION;
+    /** Format identifier; new documents use DOCUMENT_VERSION (4), without version-based rejection. */
+    version: number;
     /** Optional subject, separate from exported HTML content. */
     subject?: string;
     /** Complete body layout and style settings. */
@@ -276,16 +272,31 @@ interface Variable {
     value?: string;
 }
 
-/** Template keys mapped to preview values; nested objects and arrays support paths and loops. */
+/** Preview values; document data should contain structured-cloneable values. */
 interface TemplateData {
-    /** Template key mapped to a scalar, object or array. */
     [key: string]: unknown;
 }
-/** Resolves template HTML for the editor and preview while leaving stored source untouched. */
-declare function renderTemplatePreview(html: string, defaultData?: TemplateData): string;
+/** Optional diagnostic returned by a consumer's template validator. */
+interface TemplateValidationIssue {
+    message: string;
+    /** Zero-based character offset in the original template. */
+    offset?: number;
+}
+/** Synchronous template adapter; owns expression semantics and HTML escaping. */
+interface TemplateEngine {
+    /** Receives the complete template and detached data; errors propagate. */
+    render: (template: string, data: TemplateData) => string;
+    /** Optional, explicitly invoked; never blocks saving or rendering automatically. */
+    validate?: (template: string) => TemplateValidationIssue[];
+}
+/** Shared engine selection for standalone rendering and validation. */
+interface TemplateEngineOptions {
+    /** Defaults to the built-in basic engine. */
+    templateEngine?: TemplateEngine;
+}
 
 /** Complete document HTML export options. */
-interface DocumentHtmlOptions {
+interface DocumentHtmlOptions extends TemplateEngineOptions {
     /** Resolve templates for preview; default false. */
     resolveHtmlTemplates?: boolean;
     /** Exact inserted tokens and optional preview values, default []. */
@@ -439,7 +450,7 @@ interface BlockPluginOptions<Schema extends ControlSchema, Type extends string>
     type: Type;
     /** Nonempty library title. */
     title: string;
-    /** Library icon or string. */
+    /** Library React icon or HTML string; defaults to the first character of the trimmed title. */
     icon?: ReactNode | string;
     /** Library description. */
     description?: string;
@@ -498,6 +509,8 @@ interface ValidationIssue {
 }
 /** Block registration and image resource adapter options. */
 interface UseEmailEditorConfigOptions {
+    /** Shared synchronous template adapter; defaults to the basic engine. */
+    templateEngine?: TemplateEngine;
     /** Plugins created by defineBlock, default []. */
     plugins?: BlockPlugin[];
     /** All by default; false hides all; arrays filter/order; hidden nodes still render. */
@@ -507,6 +520,8 @@ interface UseEmailEditorConfigOptions {
 }
 /** Shared configuration for editing, creation and standalone export. */
 interface EmailEditorConfig {
+    /** Normalized engine used by canvas, preview and resolved HTML export. */
+    readonly templateEngine: TemplateEngine;
     /** All registered definitions including hidden builtins. */
     readonly definitions: readonly BlockPlugin[];
     /** Insertable blocks in display order. */
@@ -638,6 +653,10 @@ declare const DEFAULT_BLOCKS: BlockPlugin[];
 declare function resolveEmailBody(body?: Partial<EmailBodySettings> | null): EmailBodySettings;
 declare function createEmailDocument(blocks?: EmailBlockNode[]): EmailDocument;
 
+declare const DOCUMENT_VERSION: 4;
+declare const FONT_FAMILIES: readonly ControlOption[];
+declare const DEFAULT_EMAIL_BODY: EmailBodySettings;
+
 declare function createBlockNode(type: string, definitions?: readonly BlockDefinition[]): EmailBlockNode | null;
 
 declare const DIMENSION_CONTROLS: {
@@ -677,12 +696,12 @@ declare function createDecorationControls(overrides?: StyleControlOverrideMap<De
 declare function createTypographyControls(overrides?: StyleControlOverrideMap<TypographyControlName>): Record<TypographyControlName, StyleControlConfig>;
 
 /** Single-block rendering options; must be an object. */
-interface BlockRenderOptions {
+interface BlockRenderOptions extends TemplateEngineOptions {
     /** Resolve templates, default false; single-block rendering does not auto-merge variables. */
     resolveHtmlTemplate?: boolean;
     /** Explicit preview data; defaults to node defaultData. */
     templateData?: TemplateData;
-    /** Exact token dot normalization on export; merge preview data explicitly. */
+    /** Exact token dot normalization before export or preview; merge preview data explicitly. */
     variables?: Variable[];
     /** Body defaults; defaults to DEFAULT_EMAIL_BODY. */
     body?: EmailBodySettings;
@@ -694,6 +713,14 @@ declare function renderBlockContent(node: EmailBlockNode, definitions?: readonly
 declare function renderBlock(node: EmailBlockNode, definitions?: readonly BlockDefinition[], mode?: RenderMode, body?: EmailBodySettings): string;
 declare function blockToHtml(node: EmailBlockNode, definitions?: readonly BlockDefinition[], mode?: RenderMode, options?: BlockRenderOptions): string;
 
+/** Resolve a preview with one engine; stored source is never modified. */
+declare function renderTemplatePreview(template: string, data?: TemplateData, options?: TemplateEngineOptions): string;
+/** Undefined means the selected engine does not provide validation; [] means valid. */
+declare function validateTemplate(template: string, options?: TemplateEngineOptions): TemplateValidationIssue[] | undefined;
+
+/** Basic paths and control statements; unsupported input is preserved in full. */
+declare const defaultTemplateEngine: TemplateEngine;
+
 declare function buildRenderContext(node: EmailBlockNode, mode: RenderMode, body?: EmailBodySettings, definition?: BlockDefinition | undefined): BlockRenderContext;
 
 declare function getBlockDefinition(type: string, definitions?: readonly BlockDefinition[]): BlockDefinition | undefined;
@@ -861,4 +888,4 @@ interface ControlEditorProps {
 /** Reuse declared controls, image pickers and validation inside a plugin inspector. */
 declare function ControlEditor({ control }: ControlEditorProps): react.JSX.Element;
 
-export { BLOCK_TYPES, BORDER_STYLES, type BlockInspectorSection, type BlockPlugin, type BlockPluginOptions, type BlockRenderContext, type BlockRenderOptions, type BorderStyle, type BuiltinBlockType, Button, CheckboxControl, ColorControl, type ControlComponentProps, type ControlDefinition, ControlEditor, type ControlEditorProps, type ControlKind, type ControlOption, type ControlOptions, type ControlSchema, type ControlValues, DEFAULT_BLOCKS, DEFAULT_EMAIL_BODY, DOCUMENT_VERSION, type DecorationControlName, type DimensionControlName, type DocumentHtmlOptions, EditableRichText, type EditableRichTextProps, type EmailBlockNode, type EmailBlockStyle, type EmailBodySettings, EmailControls, type EmailDecorationStyle, type EmailDocument, EmailEditor, type EmailEditorConfig, type EmailEditorData, type EmailEditorInstance, type EmailEditorProps, type EmailEditorState, type EmailElementStyle, type EmailMarkup, type EmailSpacingStyle, type EmailTools, type EmailTypographyStyle, FONT_FAMILIES, FONT_WEIGHTS, type FontWeight, HORIZONTAL_ALIGNS, type HorizontalAlign, type ImagePickerContext, LINK_DECORATIONS, type LinkDecoration, type PluginEditorProps, type PluginRenderContext, RangeControl, type RenderMode, RichText, type RichTextProfile, STYLE_GROUPS, SelectControl, type StyleControlConfig, type StyleControlType, type StyleGroup, TEXT_ALIGNS, type TemplateData, type TextAlign, TextInput, type TypographyControlName, type UseEmailEditorConfigOptions, type UseEmailEditorOptions, type ValidationIssue, type Variable, blockToHtml, buildRenderContext, createBlockNode, createDecorationControls, createDimensionControls, createEmailDocument, createTypographyControls, defineBlock, documentToHtml, generateId, getBlockDefinition, mergeTemplateData, renderBlock, renderBlockContent, renderTemplatePreview, resolveEmailBody, useEmailEditor, useEmailEditorConfig, useEmailEditorState, variablesToTemplateData };
+export { BLOCK_TYPES, BORDER_STYLES, type BlockInspectorSection, type BlockPlugin, type BlockPluginOptions, type BlockRenderContext, type BlockRenderOptions, type BorderStyle, type BuiltinBlockType, Button, CheckboxControl, ColorControl, type ControlComponentProps, type ControlDefinition, ControlEditor, type ControlEditorProps, type ControlKind, type ControlOption, type ControlOptions, type ControlSchema, type ControlValues, DEFAULT_BLOCKS, DEFAULT_EMAIL_BODY, DOCUMENT_VERSION, type DecorationControlName, type DimensionControlName, type DocumentHtmlOptions, EditableRichText, type EditableRichTextProps, type EmailBlockNode, type EmailBlockStyle, type EmailBodySettings, EmailControls, type EmailDecorationStyle, type EmailDocument, EmailEditor, type EmailEditorConfig, type EmailEditorData, type EmailEditorInstance, type EmailEditorProps, type EmailEditorState, type EmailElementStyle, type EmailMarkup, type EmailSpacingStyle, type EmailTools, type EmailTypographyStyle, FONT_FAMILIES, FONT_WEIGHTS, type FontWeight, HORIZONTAL_ALIGNS, type HorizontalAlign, type ImagePickerContext, LINK_DECORATIONS, type LinkDecoration, type PluginEditorProps, type PluginRenderContext, RangeControl, type RenderMode, RichText, type RichTextProfile, STYLE_GROUPS, SelectControl, type StyleControlConfig, type StyleControlType, type StyleGroup, TEXT_ALIGNS, type TemplateData, type TemplateEngine, type TemplateEngineOptions, type TemplateValidationIssue, type TextAlign, TextInput, type TypographyControlName, type UseEmailEditorConfigOptions, type UseEmailEditorOptions, type ValidationIssue, type Variable, blockToHtml, buildRenderContext, createBlockNode, createDecorationControls, createDimensionControls, createEmailDocument, createTypographyControls, defaultTemplateEngine, defineBlock, documentToHtml, generateId, getBlockDefinition, mergeTemplateData, renderBlock, renderBlockContent, renderTemplatePreview, resolveEmailBody, useEmailEditor, useEmailEditorConfig, useEmailEditorState, validateTemplate, variablesToTemplateData };