@standhigher/react-email-editor 0.1.0 → 0.3.0

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";
@@ -32,44 +32,35 @@ declare const LINK_DECORATIONS: {
 };
 type LinkDecoration = (typeof LINK_DECORATIONS)[keyof typeof LINK_DECORATIONS];
 
-declare const DOCUMENT_VERSION: 1;
-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 {
+/** 邮件主体布局、外观和可继承的基础文字与链接样式。 */
+interface EmailBodySettings {
     textColor: string;
-    textAlign: TextAlign;
     backgroundColor: string;
     contentWidth: number;
-    contentAlign: HorizontalAlign;
     fontFamily: string;
     fontWeight: FontWeight;
-    contentBackgroundColor: string;
-    contentPadding: string;
-    outerPadding: string;
-    blockGap: string;
-    defaultFontSize: string;
-    defaultLineHeight: string;
-    paragraphSpacing: string;
-    listSpacing: string;
-    listIndent: string;
     linkColor: string;
     linkDecoration: LinkDecoration;
+    contentPadding: string;
+    blockGap: string;
     borderWidth: string;
     borderStyle: BorderStyle;
     borderColor: string;
-    borderRadius: string;
 }
 interface EmailDocument {
     version: typeof DOCUMENT_VERSION;
     subject?: string;
-    global: EmailGlobalSettings;
+    body: EmailBodySettings;
     blocks: EmailBlockNode[];
 }
 interface EmailBlockNode {
     id: string;
     type: string;
-    fields: Record<string, unknown>;
+    controls: Record<string, unknown>;
     style?: EmailBlockStyle;
     defaultData?: Record<string, unknown>;
 }
@@ -94,7 +85,7 @@ interface EmailTypographyStyle {
     linkDecoration?: LinkDecoration;
 }
 /** 按钮、图片和分割线自身的样式，与区块容器样式独立。 */
-interface EmailElementStyle extends EmailDecorationStyle, EmailTypographyStyle {
+interface EmailElementStyle extends EmailDecorationStyle {
     padding?: string;
     width?: string;
     height?: string;
@@ -103,42 +94,33 @@ interface EmailElementStyle extends EmailDecorationStyle, EmailTypographyStyle {
 interface EmailSpacingStyle {
     padding?: string;
     margin?: string;
-    /** 内层单元格高度，只使用 px。缺省时不输出 height。 */
+    /** 自定义区块可通过 styleControls 启用；内置区块不支持。只使用 px。 */
     height?: string;
 }
 interface EmailBlockStyle {
     dimension?: EmailSpacingStyle;
+    /** 自定义区块可显式启用；内置区块的文字格式存于 controls.html。 */
     typography?: EmailTypographyStyle;
     decorations?: EmailDecorationStyle;
     element?: EmailElementStyle;
 }
 
-type FieldType = "text" | "textarea" | "html" | "url" | "number" | "color" | "select";
-interface FieldOption {
+interface ControlOption {
     label: string;
     value: string;
 }
-interface FieldConfig {
-    type: FieldType;
+interface ControlConfig extends ControlDefinition {
     name: string;
-    label: string;
-    defaultValue?: unknown;
-    placeholder?: string;
-    options?: FieldOption[];
-    rows?: number;
-    min?: number;
-    max?: number;
-    step?: number;
 }
 type StyleGroup = "general" | "dimension" | "typography" | "decorations";
 type StyleControlType = "text" | "color" | "alignment" | "select" | "number" | "range" | "spacing" | "corners";
-interface StyleFieldConfig {
+interface StyleControlConfig {
     /** e.g. "typography.fontSize" — which style slot this reads and writes */
     id: string;
     group: StyleGroup;
     label: string;
     control: StyleControlType;
-    options?: FieldOption[];
+    options?: ControlOption[];
     /** Unit suffix for a single-unit slider, e.g. "px". Omit for unitless values. */
     unit?: string;
     /** Email-safe units. A select appears only when more than one is listed. */
@@ -152,28 +134,40 @@ interface StyleFieldConfig {
 type RenderMode = "canvas" | "email";
 interface BlockRenderContext {
     block: EmailBlockNode;
-    fields: Record<string, unknown>;
+    controls: Record<string, unknown>;
     style: EmailBlockStyle;
     /** canvas/email identify the consumer; HTML template resolution is applied by the shared renderer. */
     mode: RenderMode;
-    global: EmailGlobalSettings;
+    body: EmailBodySettings;
+}
+type RichTextProfile = "text" | "heading" | "button";
+/** 显式控制检查器的分组及字段归属，分组按声明顺序展示。 */
+interface BlockInspectorSection {
+    title: string;
+    controlNames?: string[];
+    styleIds?: string[];
+    advancedStyleIds?: string[];
 }
 interface BlockDefinition {
     type: string;
     title: string;
     icon?: ReactNode | string;
     description?: string;
-    fields?: FieldConfig[];
-    styleFields?: StyleFieldConfig[];
-    /** getBlockDefinition 只保留 styleFields，不补容器间距和装饰。 */
-    exactStyleFields?: boolean;
-    defaultFields?: Record<string, unknown>;
+    controls?: ControlConfig[];
+    styleControls?: StyleControlConfig[];
+    inspectorSections?: BlockInspectorSection[];
+    readControls: (value: Record<string, unknown>) => Record<string, unknown>;
+    override?: boolean;
     defaultStyle?: EmailBlockStyle;
     /** Sample data used to render template HTML in the editor and preview. */
     defaultData?: Record<string, unknown>;
-    /** Content is edited inline on the canvas and stored in fields.html. */
-    inlineEdit?: boolean;
-    render: (ctx: BlockRenderContext) => string;
+    /** 默认画布直接编辑的 richText 字段；由字段声明解析生成。 */
+    inlineControl?: string;
+    /** Optional React inspector for controls that need domain-specific editing UI. */
+    inspector?: ComponentType<PluginEditorProps>;
+    /** Optional React canvas for multi-region or interactive editing. */
+    canvas?: ComponentType<PluginEditorProps>;
+    renderEmail: (ctx: BlockRenderContext) => string;
 }
 interface Variable {
     /** 下拉展示并插入的变量，例如 `{{  store_name }}`。 */
@@ -184,6 +178,150 @@ interface Variable {
     value?: string;
 }
 
+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?: readonly BlockDefinition[], options?: DocumentHtmlOptions): string;
+
+declare const EMAIL_MARKUP: unique symbol;
+interface EmailMarkup {
+    readonly [EMAIL_MARKUP]: true;
+    readonly html: string;
+}
+interface EmailImageOptions {
+    src: string;
+    alt?: string;
+    width?: string;
+}
+interface EmailButtonOptions {
+    href: string;
+    label: string;
+}
+interface EmailTools {
+    html: (strings: TemplateStringsArray, ...values: unknown[]) => EmailMarkup;
+    raw: (html: string) => EmailMarkup;
+    richText: (html: string) => EmailMarkup;
+    table: (rows: EmailMarkup[][]) => EmailMarkup;
+    image: (options: EmailImageOptions) => EmailMarkup;
+    button: (options: EmailButtonOptions) => EmailMarkup;
+    url: (value: string, image?: boolean) => string;
+}
+
+type ControlKind = "text" | "textarea" | "html" | "richText" | "url" | "image" | "number" | "color" | "select" | "boolean" | "list" | "custom";
+interface ControlComponentProps<T = unknown> {
+    value: T;
+    onChange: (value: T) => void;
+    label: string;
+    body: EmailBodySettings;
+    variables: Variable[];
+}
+interface ControlOptions<T> {
+    label: string;
+    defaultValue?: T;
+    placeholder?: string;
+    options?: ControlOption[];
+    rows?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    profile?: RichTextProfile;
+    /** 由默认画布直接编辑此字段；多区域布局使用 Canvas + EditableRichText。 */
+    inline?: boolean;
+    component?: ComponentType<ControlComponentProps<T>>;
+    validate?: (value: T) => string | undefined;
+}
+/** 工厂生成的字段，同时负责默认值、运行时窄化和可选自定义控件。 */
+interface ControlDefinition<T = unknown> extends Omit<ControlOptions<T>, "component" | "validate"> {
+    kind: ControlKind;
+    defaultValue: T;
+    read: (value: unknown) => T;
+    /** 只接收已归一化的字段值，不重复调用 read。 */
+    validateValue?: (value: unknown) => string | undefined;
+    /** value 已由宿主归一化。 */
+    renderControl?: (props: ControlComponentProps) => ReactNode;
+    itemControls?: ControlSchema;
+}
+type ControlSchema = Record<string, ControlDefinition>;
+type ControlValues<Schema extends ControlSchema> = {
+    [Name in keyof Schema]: ReturnType<Schema[Name]["read"]>;
+};
+interface PluginEditorProps<Controls = Record<string, unknown>> {
+    block: EmailBlockNode;
+    controls: Controls;
+    style: EmailBlockStyle;
+    body: EmailBodySettings;
+    variables: Variable[];
+    selected: boolean;
+    renderedHtml: string;
+    select: () => void;
+    setControl: <Name extends keyof Controls & string>(name: Name, value: Controls[Name]) => void;
+    setControls: (patch: Partial<Controls>) => void;
+    setStyle: (id: string, value: string) => void;
+}
+interface PluginRenderContext<Controls> extends Omit<BlockRenderContext, "controls"> {
+    controls: Controls;
+    email: EmailTools;
+}
+interface BlockPluginOptions<Schema extends ControlSchema, Type extends string> {
+    type: Type;
+    title: string;
+    icon?: ReactNode | string;
+    description?: string;
+    override?: boolean;
+    controls?: Schema;
+    /** 默认 spacing + appearance；false 禁用默认容器控件。 */
+    containerStyles?: boolean | {
+        spacing?: boolean;
+        appearance?: boolean;
+    };
+    styleControls?: StyleControlConfig[];
+    inspectorSections?: BlockInspectorSection[];
+    defaultStyle?: EmailBlockStyle;
+    defaultData?: Record<string, unknown>;
+    Canvas?: ComponentType<PluginEditorProps<ControlValues<Schema>>>;
+    Inspector?: ComponentType<PluginEditorProps<ControlValues<Schema>>>;
+    renderEmail: (ctx: PluginRenderContext<ControlValues<Schema>>) => string | EmailMarkup;
+}
+/** 只通过 defineBlock 创建；配置同时用于编辑、节点创建和邮件导出。 */
+interface BlockPlugin<Schema extends ControlSchema = ControlSchema, Type extends string = string> extends BlockDefinition {
+    type: Type;
+    schema: Schema;
+}
+interface ImagePickerContext {
+    value: string;
+    label: string;
+    signal: AbortSignal;
+}
+interface ValidationIssue {
+    blockId: string;
+    blockType: string;
+    controlPath: string;
+    message: string;
+}
+interface EmailEditorConfigOptions {
+    plugins?: BlockPlugin[];
+    /** false 隐藏全部内置区块；数组声明显示顺序。隐藏不影响已有节点渲染。 */
+    builtins?: false | string[];
+    pickImage?: (context: ImagePickerContext) => Promise<string | null>;
+}
+interface EmailEditorConfig {
+    readonly definitions: readonly BlockPlugin[];
+    readonly library: readonly BlockPlugin[];
+    readonly pickImage?: EmailEditorConfigOptions["pickImage"];
+    createBlock: (type: string) => EmailBlockNode;
+    toHtml: (document: EmailDocument, options?: DocumentHtmlOptions) => string;
+    validate: (document: EmailDocument) => ValidationIssue[];
+}
+
 interface EmailEditorData {
     document: EmailDocument;
     json: string;
@@ -199,13 +337,13 @@ interface EmailEditorHandle {
 }
 interface EmailEditorProps {
     initialDocument?: EmailDocument;
-    /** External global settings. Incoming changes are applied to the open document. */
-    global?: Partial<EmailGlobalSettings>;
-    blocks?: BlockDefinition[];
+    /** External body settings. Incoming changes are applied to the open document. */
+    body?: Partial<EmailBodySettings>;
+    config?: EmailEditorConfig;
     variables?: Variable[];
     height?: number | string;
     onChange?: (document: EmailDocument) => void;
-    onGlobalChange?: (global: EmailGlobalSettings) => void;
+    onBodyChange?: (body: EmailBodySettings) => void;
 }
 
 declare const EmailEditor: react.ForwardRefExoticComponent<EmailEditorProps & react.RefAttributes<EmailEditorHandle>>;
@@ -217,91 +355,83 @@ interface RichTextInheritedStyle {
     fontWeight: FontWeight;
     lineHeight: string;
     paragraphSpacing: string;
+    listSpacing?: string;
+    listIndent?: string;
+    linkColor?: string;
+    linkDecoration?: string;
 }
 
 interface RichTextProps {
     initialHtml: string;
+    profile?: RichTextProfile;
     placeholder?: string;
     variables: Variable[];
     selected: boolean;
+    toolbarId: string;
+    toolbarCollapsed: boolean;
     inherited?: RichTextInheritedStyle;
     onCommit: (html: string) => void;
     onSelect: () => void;
 }
-declare function RichText({ initialHtml, placeholder, variables, selected, inherited, onCommit, onSelect, }: RichTextProps): react.JSX.Element;
+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;
+type DimensionControlName = keyof typeof DIMENSION_CONTROLS;
+type DecorationControlName = keyof typeof DECORATION_CONTROLS;
+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>;
 
 interface BlockRenderOptions {
     resolveHtmlTemplate?: boolean;
     templateData?: TemplateData;
     variables?: Variable[];
-    global?: EmailGlobalSettings;
+    body?: EmailBodySettings;
 }
 type BlockRenderOptionsInput = BlockRenderOptions | boolean;
 /** 用变量 name 里的字段名作为键，value 作为预览替换值。 */
 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?: BlockRenderOptionsInput): 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?: BlockRenderOptionsInput): string;
 
-declare function buildRenderContext(node: EmailBlockNode, mode: RenderMode, global?: EmailGlobalSettings): 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;
 
@@ -322,4 +452,95 @@ declare const BLOCK_TYPES: {
 };
 type BuiltinBlockType = (typeof BLOCK_TYPES)[keyof typeof BLOCK_TYPES];
 
-export { BLOCK_TYPES, BORDER_STYLES, type BlockDefinition, 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, 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: Schema;
+    }): ControlDefinition<ControlValues<Schema>[]>;
+    custom<T>(options: ControlOptions<T> & {
+        defaultValue: T;
+        read: (value: unknown) => T;
+        component: NonNullable<ControlOptions<T>["component"]>;
+    }): ControlDefinition<T>;
+};
+
+declare function createEmailEditorConfig(options?: EmailEditorConfigOptions): EmailEditorConfig;
+
+interface EditableRichTextProps {
+    control: string;
+    profile?: RichTextProfile;
+    placeholder?: string;
+}
+declare function EditableRichText({ control, profile, placeholder }: EditableRichTextProps): react.JSX.Element;
+
+interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+    type?: "text" | "url" | "email" | "search" | "tel" | "password" | "number";
+}
+declare const TextInput: react.ForwardRefExoticComponent<TextInputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface SelectControlProps {
+    id?: string;
+    label?: string;
+    value: string;
+    options: readonly ControlOption[];
+    emptyLabel?: string;
+    compact?: boolean;
+    disabled?: boolean;
+    onChange: (value: string) => void;
+}
+declare function SelectControl({ id, label, value, options, emptyLabel, compact, disabled, onChange }: SelectControlProps): react.JSX.Element;
+
+interface CheckboxControlProps {
+    label: string;
+    checked: boolean;
+    disabled?: boolean;
+    className?: string;
+    variant?: "checkbox" | "switch";
+    onChange: (checked: boolean) => void;
+}
+declare function CheckboxControl({ label, checked, disabled, className, variant, onChange }: CheckboxControlProps): react.JSX.Element;
+
+interface ColorControlProps {
+    value: string;
+    fallback?: string;
+    label?: string;
+    resetTo?: string;
+    onChange: (value: string) => void;
+}
+declare function ColorControl({ value, fallback, label, resetTo, onChange }: ColorControlProps): react.JSX.Element;
+
+interface RangeControlProps {
+    id?: string;
+    label?: string;
+    value: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    onChange: (value: number) => void;
+}
+declare function RangeControl({ id, label, value, min, max, step, onChange, }: RangeControlProps): react.JSX.Element;
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: "default" | "primary" | "solid" | "icon";
+    tooltip?: string;
+}
+declare function Button({ type, variant, className, tooltip, children, "aria-describedby": describedBy, ...props }: ButtonProps): react.JSX.Element;
+
+interface ControlEditorProps {
+    control: string;
+}
+/** 自定义 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 EmailEditorConfigOptions, type EmailEditorData, type EmailEditorHandle, type EmailEditorProps, 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 ValidationIssue, type Variable, blockToHtml, buildRenderContext, createBlockNode, createDecorationControls, createDimensionControls, createEmailDocument, createEmailEditorConfig, createTypographyControls, defineBlock, documentToHtml, generateId, getBlockDefinition, mergeTemplateData, renderBlock, renderBlockContent, renderTemplatePreview, resolveEmailBody, variablesToTemplateData };