@standhigher/react-email-editor 0.2.0 → 0.4.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, ComponentType, InputHTMLAttributes, ButtonHTMLAttributes } from 'react';
 
 declare const TEXT_ALIGNS: {
     readonly left: "left";
@@ -7,17 +7,20 @@ declare const TEXT_ALIGNS: {
     readonly right: "right";
     readonly justify: "justify";
 };
+/** Text alignment: left, center, right, justify. */
 type TextAlign = (typeof TEXT_ALIGNS)[keyof typeof TEXT_ALIGNS];
 declare const HORIZONTAL_ALIGNS: {
     readonly left: "left";
     readonly center: "center";
     readonly right: "right";
 };
+/** Element alignment: left, center, right. */
 type HorizontalAlign = (typeof HORIZONTAL_ALIGNS)[keyof typeof HORIZONTAL_ALIGNS];
 declare const FONT_WEIGHTS: {
     readonly normal: "normal";
     readonly bold: "bold";
 };
+/** Font weight: normal or bold. */
 type FontWeight = (typeof FONT_WEIGHTS)[keyof typeof FONT_WEIGHTS];
 declare const BORDER_STYLES: {
     readonly none: "none";
@@ -25,306 +28,683 @@ declare const BORDER_STYLES: {
     readonly dashed: "dashed";
     readonly dotted: "dotted";
 };
+/** Border style: none, solid, dashed, dotted. */
 type BorderStyle = (typeof BORDER_STYLES)[keyof typeof BORDER_STYLES];
 declare const LINK_DECORATIONS: {
     readonly underline: "underline";
     readonly none: "none";
 };
+/** Link decoration: underline or 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;
+declare const DOCUMENT_VERSION: 4;
+declare const FONT_FAMILIES: readonly ControlOption[];
+declare const DEFAULT_EMAIL_BODY: EmailBodySettings;
 
-interface EmailGlobalSettings {
+/** Email body layout and inherited defaults. */
+interface EmailBodySettings {
+    /** Default text color. */
     textColor: string;
-    textAlign: TextAlign;
+    /** Centered content background; outer area is white. */
     backgroundColor: string;
+    /** Maximum content width in px, normalized to an integer from 320 to 900. */
     contentWidth: number;
-    contentAlign: HorizontalAlign;
+    /** Default CSS font stack. */
     fontFamily: string;
+    /** Default font weight: normal or bold. */
     fontWeight: FontWeight;
-    contentBackgroundColor: string;
-    contentPadding: string;
-    outerPadding: string;
-    blockGap: string;
-    defaultFontSize: string;
-    defaultLineHeight: string;
-    paragraphSpacing: string;
-    listSpacing: string;
-    listIndent: string;
+    /** Color of links without explicit formatting. */
     linkColor: string;
+    /** Default link decoration: underline or none. */
     linkDecoration: LinkDecoration;
+    /** CSS padding inside the content border. */
+    contentPadding: string;
+    /** CSS length between adjacent blocks. */
+    blockGap: string;
+    /** Content container border width. */
     borderWidth: string;
+    /** Content border style. */
     borderStyle: BorderStyle;
+    /** Content border color. */
     borderColor: string;
-    borderRadius: string;
 }
+/** Persistable email document; only v4 is supported. */
 interface EmailDocument {
+    /** Format version; must be DOCUMENT_VERSION (4). */
     version: typeof DOCUMENT_VERSION;
+    /** Optional subject, separate from exported HTML content. */
     subject?: string;
-    global: EmailGlobalSettings;
+    /** Complete body layout and style settings. */
+    body: EmailBodySettings;
+    /** Blocks in display and export order. */
     blocks: EmailBlockNode[];
 }
+/** Persisted block node without components or render functions. */
 interface EmailBlockNode {
+    /** Unique block identifier within the document. */
     id: string;
+    /** Registered plugin type. */
     type: string;
-    fields: Record<string, unknown>;
+    /** Control values keyed by the plugin schema. */
+    controls: Record<string, unknown>;
+    /** Enabled block style overrides. */
     style?: EmailBlockStyle;
+    /** Block preview data taking precedence over global data in a shallow merge. */
     defaultData?: Record<string, unknown>;
 }
+/** Container or element appearance. */
 interface EmailDecorationStyle {
+    /** Background color. */
     backgroundColor?: string;
+    /** CSS border radius. */
     borderRadius?: string;
+    /** CSS border width. */
     borderWidth?: string;
+    /** Border color. */
     borderColor?: string;
+    /** Border line style. */
     borderStyle?: BorderStyle;
 }
+/** Typography explicitly enabled by custom blocks. */
 interface EmailTypographyStyle {
+    /** CSS font stack. */
     fontFamily?: string;
+    /** CSS font size. */
     fontSize?: string;
+    /** Font weight. */
     fontWeight?: FontWeight;
+    /** Line height, including unitless multipliers. */
     lineHeight?: string;
+    /** Text color. */
     color?: string;
+    /** Horizontal text alignment. */
     textAlign?: TextAlign;
+    /** Paragraph spacing. */
     paragraphSpacing?: string;
+    /** List item spacing. */
     listSpacing?: string;
+    /** List indentation. */
     listIndent?: string;
+    /** Default link color. */
     linkColor?: string;
+    /** Default link decoration. */
     linkDecoration?: LinkDecoration;
 }
-/** 按钮、图片和分割线自身的样式，与区块容器样式独立。 */
+/** Button, image or divider styles, including appearance fields. */
 interface EmailElementStyle extends EmailDecorationStyle {
+    /** Element CSS padding. */
     padding?: string;
+    /** Element CSS width. */
     width?: string;
+    /** Element CSS height. */
     height?: string;
+    /** Element horizontal alignment within its container. */
     align?: HorizontalAlign;
 }
+/** Block container dimensions and spacing. */
 interface EmailSpacingStyle {
+    /** Container padding. */
     padding?: string;
+    /** Container outer spacing. */
     margin?: string;
-    /** 自定义区块可通过 styleFields 启用；内置区块不支持。只使用 px。 */
+    /** Fixed height in px for enabled custom blocks; unsupported by builtins. */
     height?: string;
 }
+/** Grouped styles; only plugin-enabled controls are read. */
 interface EmailBlockStyle {
+    /** Container dimensions and spacing. */
     dimension?: EmailSpacingStyle;
-    /** 自定义区块可显式启用；内置区块的文字格式存于 fields.html。 */
+    /** Optional custom typography; builtin text formatting lives in controls.html. */
     typography?: EmailTypographyStyle;
+    /** Block container appearance. */
     decorations?: EmailDecorationStyle;
+    /** Styles of the button, image or other inner element. */
     element?: EmailElementStyle;
 }
 
-type FieldType = "text" | "textarea" | "html" | "url" | "number" | "color" | "select";
-interface FieldOption {
+/** Select or alignment control option. */
+interface ControlOption {
+    /** Display label. */
     label: string;
+    /** Persisted option value. */
     value: string;
 }
-interface FieldConfig {
-    type: FieldType;
+/** Named runtime control definition. */
+interface ControlConfig extends ControlDefinition {
+    /** Key in the controls object. */
     name: string;
-    label: string;
-    defaultValue?: unknown;
-    placeholder?: string;
-    options?: FieldOption[];
-    rows?: number;
-    min?: number;
-    max?: number;
-    step?: number;
 }
+/** Inspector group identifier. */
 type StyleGroup = "general" | "dimension" | "typography" | "decorations";
+/** Union of style input kinds. */
 type StyleControlType = "text" | "color" | "alignment" | "select" | "number" | "range" | "spacing" | "corners";
-interface StyleFieldConfig {
-    /** e.g. "typography.fontSize" — which style slot this reads and writes */
+/** Inspector style control declaration. */
+interface StyleControlConfig {
+    /** Style path, e.g. dimension.padding. */
     id: string;
+    /** Default inspector group. */
     group: StyleGroup;
+    /** Display label. */
     label: string;
+    /** Style input kind. */
     control: StyleControlType;
-    options?: FieldOption[];
-    /** Unit suffix for a single-unit slider, e.g. "px". Omit for unitless values. */
+    /** Options for select or alignment. */
+    options?: ControlOption[];
+    /** Single unit suffix; omit for unitless values. */
     unit?: string;
-    /** Email-safe units. A select appears only when more than one is listed. */
+    /** Allowed email CSS units; multiple units show a selector. */
     units?: string[];
+    /** Minimum numeric or range value. */
     min?: number;
+    /** Maximum numeric or range value. */
     max?: number;
+    /** Numeric increment. */
     step?: number;
+    /** Default style string; overridden by defaultStyle. */
     defaultValue?: string;
+    /** Empty input hint. */
     placeholder?: string;
 }
+/** Canvas or email consumer mode; independent of template resolution. */
 type RenderMode = "canvas" | "email";
+/** Normalized snapshots used by block renderers. */
 interface BlockRenderContext {
+    /** Block copy with normalized controls and styles. */
     block: EmailBlockNode;
-    fields: Record<string, unknown>;
+    /** Values parsed by the plugin readControls. */
+    controls: Record<string, unknown>;
+    /** Normalized enabled styles. */
     style: EmailBlockStyle;
-    /** canvas/email identify the consumer; HTML template resolution is applied by the shared renderer. */
+    /** Canvas or email consumer; templates are processed by the shared renderer. */
     mode: RenderMode;
-    global: EmailGlobalSettings;
+    /** Copy of email body settings. */
+    body: EmailBodySettings;
 }
+/** Rich-text features for text, heading or button. */
 type RichTextProfile = "text" | "heading" | "button";
-/** 显式控制检查器的分组及字段归属，分组按声明顺序展示。 */
+/** Inspector section displayed in declaration order. */
 interface BlockInspectorSection {
+    /** Section title. */
     title: string;
-    fieldNames?: string[];
+    /** Content control names in display order. */
+    controlNames?: string[];
+    /** Style control IDs in display order. */
     styleIds?: string[];
+    /** Style IDs inside the collapsed advanced section. */
     advancedStyleIds?: string[];
 }
+/** Normalized block definition available through plugin values and registry lookups. */
 interface BlockDefinition {
+    /** Unique block type. */
     type: string;
+    /** Library title. */
     title: string;
+    /** Library React icon or string. */
     icon?: ReactNode | string;
+    /** Library description. */
     description?: string;
-    fields?: FieldConfig[];
-    styleFields?: StyleFieldConfig[];
+    /** Named controls in declaration order. */
+    controls?: ControlConfig[];
+    /** Enabled style controls. */
+    styleControls?: StyleControlConfig[];
+    /** Custom inspector sections. */
     inspectorSections?: BlockInspectorSection[];
-    /** 只启用 styleFields，不补容器间距和装饰；渲染也只读取启用的字段。 */
-    exactStyleFields?: boolean;
-    defaultFields?: Record<string, unknown>;
+    /** Parse a raw control object into normalized values. */
+    readControls: (value: Record<string, unknown>) => Record<string, unknown>;
+    /** Allow replacing a builtin with the same type. */
+    override?: boolean;
+    /** Default styles for new nodes. */
     defaultStyle?: EmailBlockStyle;
-    /** Sample data used to render template HTML in the editor and preview. */
+    /** Template preview data for new nodes. */
     defaultData?: Record<string, unknown>;
-    /** Content is edited inline on the canvas and stored in fields.html. */
-    inlineEdit?: boolean;
-    inlineEditProfile?: RichTextProfile;
-    render: (ctx: BlockRenderContext) => string;
+    /** Rich-text control edited by the default canvas. */
+    inlineControl?: string;
+    /** Inspector component bound to the editor context. */
+    inspector?: ComponentType<PluginEditorProps>;
+    /** Canvas component bound to the editor context. */
+    canvas?: ComponentType<PluginEditorProps>;
+    /** Render inner HTML from normalized context; email mode validates controls. */
+    renderEmail: (ctx: BlockRenderContext) => string;
 }
+/** Insertable template variable and preview value. */
 interface Variable {
-    /** 下拉展示并插入的变量，例如 `{{  store_name }}`。 */
+    /** Exact inserted token, e.g. {{ store_name }}; exact matches receive export dot normalization. */
     name: string;
-    /** 下拉选项副文案。空字符串或不传时不渲染。 */
+    /** Secondary option text; hidden when absent or empty. */
     description?: string;
-    /** 预览时替换该变量的文本。 */
+    /** Preview replacement text; omitted values add no preview data. */
     value?: string;
 }
 
+/** Template keys mapped to preview values; nested objects and arrays support paths and loops. */
+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;
+
+/** Complete document HTML export options. */
+interface DocumentHtmlOptions {
+    /** Resolve templates for preview; default false. */
+    resolveHtmlTemplates?: boolean;
+    /** Exact inserted tokens and optional preview values, default []. */
+    variables?: Variable[];
+    /** Global template data; shallow precedence below block defaultData and above variables. */
+    templateData?: TemplateData;
+}
+declare function documentToHtml(document: EmailDocument, definitions?: readonly BlockDefinition[], options?: DocumentHtmlOptions): string;
+
+declare const EMAIL_MARKUP: unique symbol;
+/** Branded email HTML fragment created by email tools. */
+interface EmailMarkup {
+    readonly [EMAIL_MARKUP]: true;
+    /** Fragment HTML content. */
+    readonly html: string;
+}
+/** email.image options. */
+interface EmailImageOptions {
+    /** Image URL allowing http, https, cid or a template. */
+    src: string;
+    /** Alternative text, default empty. */
+    alt?: string;
+    /** CSS width, default 100%; invalid values use the default. */
+    width?: string;
+}
+/** email.button options. */
+interface EmailButtonOptions {
+    /** Link URL; empty or invalid values render non-link text. */
+    href: string;
+    /** Button text, automatically escaped. */
+    label: string;
+}
+/** Email HTML helpers available in plugin renderEmail. */
+interface EmailTools {
+    /** Tagged template strings and values; ordinary values are escaped, markup and arrays compose. */
+    html: (strings: TemplateStringsArray, ...values: unknown[]) => EmailMarkup;
+    /** Insert raw HTML without sanitization. */
+    raw: (html: string) => EmailMarkup;
+    /** Preserve rich-text formatting and apply body defaults. */
+    richText: (html: string) => EmailMarkup;
+    /** Build a presentation table from rows of EmailMarkup cells. */
+    table: (rows: EmailMarkup[][]) => EmailMarkup;
+    /** Render an image from URL, alt and width, validating protocols and escaping. */
+    image: (options: EmailImageOptions) => EmailMarkup;
+    /** Render an email table button from URL and label. */
+    button: (options: EmailButtonOptions) => EmailMarkup;
+    /** Validate a URL; image selects image protocols, default false; invalid URLs return empty. */
+    url: (value: string, image?: boolean) => string;
+}
+
+/** Content control kind. */
+type ControlKind = "text" | "textarea" | "html" | "richText" | "url" | "image" | "number" | "color" | "select" | "boolean" | "list" | "custom";
+/** Custom control props; T is the value type. */
+interface ControlComponentProps<T = unknown> {
+    /** Detached normalized control value. */
+    value: T;
+    /** Submit the new control value. */
+    onChange: (value: T) => void;
+    /** Declared control label. */
+    label: string;
+    /** Current body settings snapshot. */
+    body: EmailBodySettings;
+    /** Insertable variable snapshots. */
+    variables: Variable[];
+}
+/** Control factory options; T is the default/edit value type. */
+interface ControlOptions<T> {
+    /** Required display label. */
+    label: string;
+    /** Factory fallback when omitted; persisted undefined receives the default. */
+    defaultValue?: T;
+    /** Empty input hint. */
+    placeholder?: string;
+    /** Allowed select options. */
+    options?: ControlOption[];
+    /** Visible textarea or HTML editor rows. */
+    rows?: number;
+    /** Minimum number or list length. */
+    min?: number;
+    /** Maximum number or list length. */
+    max?: number;
+    /** Number input increment. */
+    step?: number;
+    /** Unit label beside a numeric input. */
+    unit?: string;
+    /** Rich-text feature profile: text, heading or button. */
+    profile?: RichTextProfile;
+    /** Edit this richText on the default canvas; multiple regions require Canvas. */
+    inline?: boolean;
+    /** Custom React control component. */
+    component?: ComponentType<ControlComponentProps<T>>;
+    /** Validate a normalized value; return an error message or undefined. */
+    validate?: (value: T) => string | undefined;
+}
+/** Factory-produced control definition; T is its parsed value type. */
+interface ControlDefinition<T = unknown> extends Omit<ControlOptions<T>, "component" | "validate"> {
+    /** Control kind. */
+    kind: ControlKind;
+    /** Normalized default value. */
+    defaultValue: T;
+    /** Parse an unknown persisted value into T; must be pure. */
+    read: (value: unknown) => T;
+    /** Validate an already normalized value without re-reading. */
+    validateValue?: (value: unknown) => string | undefined;
+    /** Render React UI from host-normalized control props. */
+    renderControl?: (props: ControlComponentProps) => ReactNode;
+    /** Child control schema for each list row. */
+    itemControls?: ControlSchema;
+}
+/** Map from control names to definitions. */
+type ControlSchema = Record<string, ControlDefinition>;
+/** Infer values from each Schema control read return type. */
+type ControlValues<Schema extends ControlSchema> = {
+    [Name in keyof Schema]: ReturnType<Schema[Name]["read"]>;
+};
+/** Canvas or Inspector props; Controls is the inferred value shape. */
+interface PluginEditorProps<Controls = Record<string, unknown>> {
+    /** Detached block snapshot. */
+    block: EmailBlockNode;
+    /** Normalized control value snapshot. */
+    controls: Controls;
+    /** Current enabled styles snapshot. */
+    style: EmailBlockStyle;
+    /** Body settings snapshot. */
+    body: EmailBodySettings;
+    /** Available variable snapshots. */
+    variables: Variable[];
+    /** Whether selected; true inside Inspector. */
+    selected: boolean;
+    /** Resolved inner HTML in Canvas; empty in Inspector. */
+    renderedHtml: string;
+    /** Request selection of this block. */
+    select: () => void;
+    /** Update the named control with its typed value. */
+    setControl: <Name extends keyof Controls & string>(name: Name, value: Controls[Name]) => void;
+    /** Shallow-merge a patch in one update; replace nested values entirely. */
+    setControls: (patch: Partial<Controls>) => void;
+    /** Update a style path with a CSS string. */
+    setStyle: (id: string, value: string) => void;
+}
+/** Typed email render context; Controls contains inferred values. */
+interface PluginRenderContext<Controls> extends Omit<BlockRenderContext, "controls"> {
+    /** Inferred normalized control values. */
+    controls: Controls;
+    /** Escaping and layout helpers for email HTML. */
+    email: EmailTools;
+}
+/** defineBlock options; Schema infers values and Type preserves the type literal. */
+interface BlockPluginOptions<Schema extends ControlSchema, Type extends string> {
+    /** Nonempty unique type; a business prefix is recommended. */
+    type: Type;
+    /** Nonempty library title. */
+    title: string;
+    /** Library icon or string. */
+    icon?: ReactNode | string;
+    /** Library description. */
+    description?: string;
+    /** Must be true to replace a builtin. */
+    override?: boolean;
+    /** Control schema, default {}. */
+    controls?: Schema;
+    /** Container styles enabled by default; false disables all; spacing and appearance select groups. */
+    containerStyles?: boolean | {
+        /** Enable default padding and margin controls; default true. */
+        spacing?: boolean;
+        /** Enable default background and border controls; default true. */
+        appearance?: boolean;
+    };
+    /** Extra style controls; matching IDs replace container controls. */
+    styleControls?: StyleControlConfig[];
+    /** Ordered content and style sections. */
+    inspectorSections?: BlockInspectorSection[];
+    /** Initial styles, taking precedence over control defaultValue. */
+    defaultStyle?: EmailBlockStyle;
+    /** Template preview data for new nodes. */
+    defaultData?: Record<string, unknown>;
+    /** Optional React canvas composing multiple editing regions. */
+    Canvas?: ComponentType<PluginEditorProps<ControlValues<Schema>>>;
+    /** Optional React inspector replacing the default content editor. */
+    Inspector?: ComponentType<PluginEditorProps<ControlValues<Schema>>>;
+    /** Render inner HTML or EmailMarkup from typed context, without editor UI. */
+    renderEmail: (ctx: PluginRenderContext<ControlValues<Schema>>) => string | EmailMarkup;
+}
+/** Plugin returned by defineBlock; Schema is its schema and Type its identifier type. */
+interface BlockPlugin<Schema extends ControlSchema = ControlSchema, Type extends string = string> extends BlockDefinition {
+    /** Block type literal. */
+    type: Type;
+    /** Detached frozen snapshot of the control schema. */
+    schema: Schema;
+}
+/** Image resource picker request. */
+interface ImagePickerContext {
+    /** Current image URL. */
+    value: string;
+    /** Label of the requesting control. */
+    label: string;
+    /** Cancellation signal on unmount or invalidation; pass to resource requests. */
+    signal: AbortSignal;
+}
+/** Document control validation issue. */
+interface ValidationIssue {
+    /** Invalid block ID. */
+    blockId: string;
+    /** Invalid plugin type. */
+    blockType: string;
+    /** Control path including list row indexes and child controls. */
+    controlPath: string;
+    /** Displayable error description. */
+    message: string;
+}
+/** Block registration and image resource adapter options. */
+interface UseEmailEditorConfigOptions {
+    /** Plugins created by defineBlock, default []. */
+    plugins?: BlockPlugin[];
+    /** All by default; false hides all; arrays filter/order; hidden nodes still render. */
+    builtins?: false | string[];
+    /** Resolve a URL from context, return null to cancel, or throw to show retry. */
+    pickImage?: (context: ImagePickerContext) => Promise<string | null>;
+}
+/** Shared configuration for editing, creation and standalone export. */
+interface EmailEditorConfig {
+    /** All registered definitions including hidden builtins. */
+    readonly definitions: readonly BlockPlugin[];
+    /** Insertable blocks in display order. */
+    readonly library: readonly BlockPlugin[];
+    /** Optional image resource picker. */
+    readonly pickImage?: UseEmailEditorConfigOptions["pickImage"];
+    /** Create a detached default node for a registered type; unknown types throw. */
+    createBlock: (type: string) => EmailBlockNode;
+    /** Export a v4 document using this configuration and optional template options. */
+    toHtml: (document: EmailDocument, options?: DocumentHtmlOptions) => string;
+    /** Return document control issues, including missing plugins. */
+    validate: (document: EmailDocument) => ValidationIssue[];
+}
+
+/** Independent export snapshot. */
 interface EmailEditorData {
+    /** Document snapshot for persistence and reloading. */
     document: EmailDocument;
+    /** Pretty-printed document JSON. */
     json: string;
+    /** Complete email HTML preserving templates. */
     html: string;
+    /** Complete HTML resolved with preview data. */
     renderedHtml: string;
 }
-interface EmailEditorHandle {
+/** Stable editor instance independent of UI mounting. */
+interface EmailEditorInstance {
+    /** Read all export formats; rendering errors throw. */
     getData: () => EmailEditorData;
+    /** Read a detached document snapshot. */
     getDocument: () => EmailDocument;
+    /** Read pretty-printed document JSON. */
     getJson: () => string;
+    /** Export complete email HTML preserving templates. */
     getHtml: () => string;
+    /** Export HTML with current preview data. */
     getRenderedHtml: () => string;
+    /** Replace with a v4 document, clear interaction state and notify onChange. */
+    setDocument: (document: EmailDocument) => void;
+    /** Restore initialized document and body, clear interaction state and notify. */
+    reset: () => void;
+    /** Validate controls and return issues without rendering HTML. */
+    validate: () => ValidationIssue[];
 }
+/** Editor UI props. */
 interface EmailEditorProps {
+    /** Required instance created by useEmailEditor. */
+    editor: EmailEditorInstance;
+    /** Height, default 100%; numbers are px; percentages need a sized parent. */
+    height?: number | string;
+}
+type ReadonlyData<T> = T extends object ? {
+    readonly [Key in keyof T]: ReadonlyData<T[Key]>;
+} : T;
+/** Cached readonly document subscription snapshot. */
+interface EmailEditorState {
+    /** Deeply readonly document; update through instance methods. */
+    readonly document: ReadonlyData<EmailDocument>;
+}
+/** Editor initialization and reactive options. */
+interface UseEmailEditorOptions {
+    /** Read once; use setDocument for later replacements; defaults to empty. */
     initialDocument?: EmailDocument;
-    /** External global settings. Incoming changes are applied to the open document. */
-    global?: Partial<EmailGlobalSettings>;
-    blocks?: BlockDefinition[];
+    /** Initial body overrides; later changes merge into the current body. */
+    body?: Partial<EmailBodySettings>;
+    /** Block/resource configuration; defaults to all builtins; updates preserve the document. */
+    config?: EmailEditorConfig;
+    /** Insertable preview variables, default []; updates affect preview/export. */
     variables?: Variable[];
-    height?: number | string;
+    /** Detached document after changes, replacements, resets or effective body updates; no initial call. */
     onChange?: (document: EmailDocument) => void;
-    onGlobalChange?: (global: EmailGlobalSettings) => void;
+    /** Detached body snapshot after body edits inside the editor only. */
+    onBodyChange?: (body: EmailBodySettings) => void;
 }
 
-declare const EmailEditor: react.ForwardRefExoticComponent<EmailEditorProps & react.RefAttributes<EmailEditorHandle>>;
+declare function EmailEditor(props: EmailEditorProps): react.JSX.Element;
 
+/** Inherited styles for the low-level rich-text toolbar. */
 interface RichTextInheritedStyle {
+    /** Inherited font stack. */
     fontFamily: string;
+    /** Inherited font size. */
     fontSize: string;
+    /** Inherited text color. */
     color: string;
+    /** Inherited font weight. */
     fontWeight: FontWeight;
+    /** Inherited line height. */
     lineHeight: string;
+    /** Inherited paragraph spacing. */
     paragraphSpacing: string;
+    /** Inherited list item spacing. */
     listSpacing?: string;
+    /** Inherited list indentation. */
     listIndent?: string;
+    /** Inherited link color. */
     linkColor?: string;
+    /** Inherited link decoration. */
     linkDecoration?: string;
 }
 
+/** Low-level rich-text props; prefer EditableRichText in plugins. */
 interface RichTextProps {
+    /** Initial and externally synchronized HTML. */
     initialHtml: string;
+    /** Feature profile, default text. */
     profile?: RichTextProfile;
+    /** Empty hint, default Type something…. */
     placeholder?: string;
+    /** Variables available in the toolbar. */
     variables: Variable[];
+    /** Whether selected and eligible to show the toolbar. */
     selected: boolean;
+    /** Toolbar DOM ID; caller ensures uniqueness. */
     toolbarId: string;
+    /** Whether the toolbar is hidden. */
     toolbarCollapsed: boolean;
+    /** Inherited typography; defaults to internal typography. */
     inherited?: RichTextInheritedStyle;
+    /** Receive complete rich-text HTML after each edit. */
     onCommit: (html: string) => void;
+    /** Request selection on click or focus. */
     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 const DEFAULT_BLOCKS: BlockPlugin[];
 
-declare function resolveEmailGlobal(global?: Partial<EmailGlobalSettings> | null): EmailGlobalSettings;
+declare function resolveEmailBody(body?: Partial<EmailBodySettings> | null): EmailBodySettings;
 declare function createEmailDocument(blocks?: EmailBlockNode[]): EmailDocument;
 
-declare function createBlockNode(type: string, definitions?: BlockDefinition[]): EmailBlockNode | null;
+declare function createBlockNode(type: string, definitions?: readonly BlockDefinition[]): EmailBlockNode | null;
 
-declare const DIMENSION_FIELDS: {
-    padding: StyleFieldConfig;
-    margin: StyleFieldConfig;
-    height: StyleFieldConfig;
+declare const DIMENSION_CONTROLS: {
+    padding: StyleControlConfig;
+    margin: StyleControlConfig;
+    height: StyleControlConfig;
 };
-declare const DECORATION_FIELDS: {
-    backgroundColor: StyleFieldConfig;
-    borderWidth: StyleFieldConfig;
-    borderStyle: StyleFieldConfig;
-    borderColor: StyleFieldConfig;
-    borderRadius: StyleFieldConfig;
+declare const DECORATION_CONTROLS: {
+    backgroundColor: StyleControlConfig;
+    borderWidth: StyleControlConfig;
+    borderStyle: StyleControlConfig;
+    borderColor: StyleControlConfig;
+    borderRadius: StyleControlConfig;
 };
-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;
+declare const TYPOGRAPHY_CONTROL_MAP: {
+    fontFamily: StyleControlConfig;
+    fontSize: StyleControlConfig;
+    fontWeight: StyleControlConfig;
+    lineHeight: StyleControlConfig;
+    color: StyleControlConfig;
+    textAlign: StyleControlConfig;
+    paragraphSpacing: StyleControlConfig;
+    listSpacing: StyleControlConfig;
+    listIndent: StyleControlConfig;
+    linkColor: StyleControlConfig;
+    linkDecoration: StyleControlConfig;
 };
-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;
+/** Dimension names: padding, margin, height. */
+type DimensionControlName = keyof typeof DIMENSION_CONTROLS;
+/** Appearance control names. */
+type DecorationControlName = keyof typeof DECORATION_CONTROLS;
+/** Typography control names. */
+type TypographyControlName = keyof typeof TYPOGRAPHY_CONTROL_MAP;
+type StyleControlOverrideMap<Name extends string> = Partial<Record<Name, Partial<StyleControlConfig>>>;
+declare function createDimensionControls(overrides?: StyleControlOverrideMap<DimensionControlName>): Record<DimensionControlName, StyleControlConfig>;
+declare function createDecorationControls(overrides?: StyleControlOverrideMap<DecorationControlName>): Record<DecorationControlName, StyleControlConfig>;
+declare function createTypographyControls(overrides?: StyleControlOverrideMap<TypographyControlName>): Record<TypographyControlName, StyleControlConfig>;
 
+/** Single-block rendering options; must be an object. */
 interface BlockRenderOptions {
+    /** 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. */
     variables?: Variable[];
-    global?: EmailGlobalSettings;
+    /** Body defaults; defaults to DEFAULT_EMAIL_BODY. */
+    body?: EmailBodySettings;
 }
-type BlockRenderOptionsInput = BlockRenderOptions | boolean;
-/** 用变量 name 里的字段名作为键，value 作为预览替换值。 */
+/** Convert variable name paths and preview values into template data. */
 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 renderBlockContent(node: EmailBlockNode, definitions?: readonly BlockDefinition[], mode?: RenderMode, options?: BlockRenderOptions): string;
+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;
 
-declare function buildRenderContext(node: EmailBlockNode, mode: RenderMode, global?: EmailGlobalSettings, definition?: BlockDefinition | undefined): BlockRenderContext;
+declare function buildRenderContext(node: EmailBlockNode, mode: RenderMode, body?: EmailBodySettings, definition?: BlockDefinition | undefined): BlockRenderContext;
 
-declare function getBlockDefinition(type: string, definitions?: BlockDefinition[]): BlockDefinition | undefined;
+declare function getBlockDefinition(type: string, definitions?: readonly BlockDefinition[]): BlockDefinition | undefined;
 
 declare function generateId(prefix?: string): string;
 
+/** Inspector group option. */
 interface StyleGroupOption {
+    /** Group identifier. */
     group: StyleGroup;
+    /** Display label. */
     label: string;
 }
 declare const STYLE_GROUPS: StyleGroupOption[];
@@ -338,6 +718,147 @@ declare const BLOCK_TYPES: {
     readonly spacer: "spacer";
     readonly html: "html";
 };
+/** Union of builtin block type identifiers. */
 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 };
+declare function defineBlock<Schema extends ControlSchema, const Type extends string>(input: BlockPluginOptions<Schema, Type>): BlockPlugin<Schema, Type>;
+
+declare const EmailControls: {
+    text: (options: ControlOptions<string>) => ControlDefinition<string>;
+    textarea: (options: ControlOptions<string>) => ControlDefinition<string>;
+    richText: (options: ControlOptions<string>) => ControlDefinition<string>;
+    html: (options: ControlOptions<string>) => ControlDefinition<string>;
+    url: (options: ControlOptions<string>) => ControlDefinition<string>;
+    image: (options: ControlOptions<string>) => ControlDefinition<string>;
+    color: (options: ControlOptions<string>) => ControlDefinition<string>;
+    select: (options: ControlOptions<string>) => ControlDefinition<string>;
+    boolean: (options: ControlOptions<boolean>) => ControlDefinition<boolean>;
+    number: (options: ControlOptions<number>) => ControlDefinition<number>;
+    list<Schema extends ControlSchema>(options: ControlOptions<ControlValues<Schema>[]> & {
+        /** Controls for each list row; Schema infers row values. */
+        controls: Schema;
+    }): ControlDefinition<ControlValues<Schema>[]>;
+    custom<T>(options: ControlOptions<T> & {
+        /** Required default value; must be JSON-persistable. */
+        defaultValue: T;
+        /** Purely parse an unknown persisted value into T. */
+        read: (value: unknown) => T;
+        /** Required editing component receiving ControlComponentProps<T>. */
+        component: NonNullable<ControlOptions<T>["component"]>;
+    }): ControlDefinition<T>;
+};
+
+declare function useEmailEditorConfig(options?: UseEmailEditorConfigOptions): EmailEditorConfig;
+
+declare function useEmailEditor(options?: UseEmailEditorOptions): EmailEditorInstance;
+
+declare function useEmailEditorState(editor: EmailEditorInstance): EmailEditorState;
+
+/** Rich-text region within plugin context. */
+interface EditableRichTextProps {
+    /** Name of a declared richText control. */
+    control: string;
+    /** Override the control rich-text feature profile. */
+    profile?: RichTextProfile;
+    /** Override the empty editor hint. */
+    placeholder?: string;
+}
+declare function EditableRichText({ control, profile, placeholder }: EditableRichTextProps): react.JSX.Element;
+
+/** Text input props; other attributes follow React input; supports ref. */
+interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+    /** Input type, default text; excludes checkbox and other non-text kinds. */
+    type?: "text" | "url" | "email" | "search" | "tel" | "password" | "number";
+}
+declare const TextInput: react.ForwardRefExoticComponent<TextInputProps & react.RefAttributes<HTMLInputElement>>;
+
+/** String select props. */
+interface SelectControlProps {
+    /** Native select DOM ID. */
+    id?: string;
+    /** Accessible name. */
+    label?: string;
+    /** Current option value. */
+    value: string;
+    /** Options in display order. */
+    options: readonly ControlOption[];
+    /** Optional empty-option label; no duplicate empty option. */
+    emptyLabel?: string;
+    /** Compact size, default false. */
+    compact?: boolean;
+    /** Whether disabled. */
+    disabled?: boolean;
+    /** Receive the new option value. */
+    onChange: (value: string) => void;
+}
+declare function SelectControl({ id, label, value, options, emptyLabel, compact, disabled, onChange }: SelectControlProps): react.JSX.Element;
+
+/** Checkbox or switch props. */
+interface CheckboxControlProps {
+    /** Visible and accessible label. */
+    label: string;
+    /** Current checked state. */
+    checked: boolean;
+    /** Whether disabled. */
+    disabled?: boolean;
+    /** Additional root CSS class. */
+    className?: string;
+    /** Appearance: checkbox by default, or switch. */
+    variant?: "checkbox" | "switch";
+    /** Receive the new checked state. */
+    onChange: (checked: boolean) => void;
+}
+declare function CheckboxControl({ label, checked, disabled, className, variant, onChange }: CheckboxControlProps): react.JSX.Element;
+
+/** Color picker props. */
+interface ColorControlProps {
+    /** Current CSS color value. */
+    value: string;
+    /** Display fallback for an empty value, default #000000. */
+    fallback?: string;
+    /** Button and dialog label, default Color. */
+    label?: string;
+    /** Value submitted on reset; defaults to fallback. */
+    resetTo?: string;
+    /** Receive the selected or reset color. */
+    onChange: (value: string) => void;
+}
+declare function ColorControl({ value, fallback, label, resetTo, onChange }: ColorControlProps): react.JSX.Element;
+
+/** Numeric range props. */
+interface RangeControlProps {
+    /** Native input DOM ID. */
+    id?: string;
+    /** Accessible name. */
+    label?: string;
+    /** Current numeric value. */
+    value: number;
+    /** Minimum, default 0. */
+    min?: number;
+    /** Maximum, default 100. */
+    max?: number;
+    /** Increment, default 1. */
+    step?: number;
+    /** Receive the updated number. */
+    onChange: (value: number) => void;
+}
+declare function RangeControl({ id, label, value, min, max, step, onChange, }: RangeControlProps): react.JSX.Element;
+
+/** Button props; other attributes follow React button; type defaults to button. */
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Appearance: default, primary, solid or icon; default is default. */
+    variant?: "default" | "primary" | "solid" | "icon";
+    /** Optional tooltip linked through aria-describedby. */
+    tooltip?: string;
+}
+declare function Button({ type, variant, className, tooltip, children, "aria-describedby": describedBy, ...props }: ButtonProps): react.JSX.Element;
+
+/** Declared-control component props within plugin context. */
+interface ControlEditorProps {
+    /** Declared control name; unknown names throw. */
+    control: string;
+}
+/** 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 };