@standhigher/react-email-editor 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+declare const TEXT_ALIGNS: {
+    readonly left: "left";
+    readonly center: "center";
+    readonly right: "right";
+    readonly justify: "justify";
+};
+type TextAlign = (typeof TEXT_ALIGNS)[keyof typeof TEXT_ALIGNS];
+declare const HORIZONTAL_ALIGNS: {
+    readonly left: "left";
+    readonly center: "center";
+    readonly right: "right";
+};
+type HorizontalAlign = (typeof HORIZONTAL_ALIGNS)[keyof typeof HORIZONTAL_ALIGNS];
+declare const FONT_WEIGHTS: {
+    readonly normal: "normal";
+    readonly bold: "bold";
+};
+type FontWeight = (typeof FONT_WEIGHTS)[keyof typeof FONT_WEIGHTS];
+declare const BORDER_STYLES: {
+    readonly none: "none";
+    readonly solid: "solid";
+    readonly dashed: "dashed";
+    readonly dotted: "dotted";
+};
+type BorderStyle = (typeof BORDER_STYLES)[keyof typeof BORDER_STYLES];
+declare const LINK_DECORATIONS: {
+    readonly underline: "underline";
+    readonly none: "none";
+};
+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;
+
+interface EmailGlobalSettings {
+    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;
+    borderWidth: string;
+    borderStyle: BorderStyle;
+    borderColor: string;
+    borderRadius: string;
+}
+interface EmailDocument {
+    version: typeof DOCUMENT_VERSION;
+    subject?: string;
+    global: EmailGlobalSettings;
+    blocks: EmailBlockNode[];
+}
+interface EmailBlockNode {
+    id: string;
+    type: string;
+    fields: Record<string, unknown>;
+    style?: EmailBlockStyle;
+    defaultData?: Record<string, unknown>;
+}
+interface EmailDecorationStyle {
+    backgroundColor?: string;
+    borderRadius?: string;
+    borderWidth?: string;
+    borderColor?: string;
+    borderStyle?: BorderStyle;
+}
+interface EmailTypographyStyle {
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: FontWeight;
+    lineHeight?: string;
+    color?: string;
+    textAlign?: TextAlign;
+    paragraphSpacing?: string;
+    listSpacing?: string;
+    listIndent?: string;
+    linkColor?: string;
+    linkDecoration?: LinkDecoration;
+}
+/** 按钮、图片和分割线自身的样式，与区块容器样式独立。 */
+interface EmailElementStyle extends EmailDecorationStyle, EmailTypographyStyle {
+    padding?: string;
+    width?: string;
+    height?: string;
+    align?: HorizontalAlign;
+}
+interface EmailSpacingStyle {
+    padding?: string;
+    margin?: string;
+    /** 内层单元格高度，只使用 px。缺省时不输出 height。 */
+    height?: string;
+}
+interface EmailBlockStyle {
+    dimension?: EmailSpacingStyle;
+    typography?: EmailTypographyStyle;
+    decorations?: EmailDecorationStyle;
+    element?: EmailElementStyle;
+}
+
+type FieldType = "text" | "textarea" | "html" | "url" | "number" | "color" | "select";
+interface FieldOption {
+    label: string;
+    value: string;
+}
+interface FieldConfig {
+    type: FieldType;
+    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 {
+    /** e.g. "typography.fontSize" — which style slot this reads and writes */
+    id: string;
+    group: StyleGroup;
+    label: string;
+    control: StyleControlType;
+    options?: FieldOption[];
+    /** 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. */
+    units?: string[];
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultValue?: string;
+    placeholder?: string;
+}
+type RenderMode = "canvas" | "email";
+interface BlockRenderContext {
+    block: EmailBlockNode;
+    fields: Record<string, unknown>;
+    style: EmailBlockStyle;
+    /** canvas/email identify the consumer; HTML template resolution is applied by the shared renderer. */
+    mode: RenderMode;
+    global: EmailGlobalSettings;
+}
+interface BlockDefinition {
+    type: string;
+    title: string;
+    icon?: ReactNode | string;
+    description?: string;
+    fields?: FieldConfig[];
+    styleFields?: StyleFieldConfig[];
+    /** getBlockDefinition 只保留 styleFields，不补容器间距和装饰。 */
+    exactStyleFields?: boolean;
+    defaultFields?: Record<string, unknown>;
+    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;
+}
+interface Variable {
+    /** 下拉展示并插入的变量，例如 `{{  store_name }}`。 */
+    name: string;
+    /** 下拉选项副文案。空字符串或不传时不渲染。 */
+    description?: string;
+    /** 预览时替换该变量的文本。 */
+    value?: string;
+}
+
+interface EmailEditorData {
+    document: EmailDocument;
+    json: string;
+    html: string;
+    renderedHtml: string;
+}
+interface EmailEditorHandle {
+    getData: () => EmailEditorData;
+    getDocument: () => EmailDocument;
+    getJson: () => string;
+    getHtml: () => string;
+    getRenderedHtml: () => string;
+}
+interface EmailEditorProps {
+    initialDocument?: EmailDocument;
+    /** External global settings. Incoming changes are applied to the open document. */
+    global?: Partial<EmailGlobalSettings>;
+    blocks?: BlockDefinition[];
+    variables?: Variable[];
+    height?: number | string;
+    onChange?: (document: EmailDocument) => void;
+    onGlobalChange?: (global: EmailGlobalSettings) => void;
+}
+
+declare const EmailEditor: react.ForwardRefExoticComponent<EmailEditorProps & react.RefAttributes<EmailEditorHandle>>;
+
+interface RichTextInheritedStyle {
+    fontFamily: string;
+    fontSize: string;
+    color: string;
+    fontWeight: FontWeight;
+    lineHeight: string;
+    paragraphSpacing: string;
+}
+
+interface RichTextProps {
+    initialHtml: string;
+    placeholder?: string;
+    variables: Variable[];
+    selected: boolean;
+    inherited?: RichTextInheritedStyle;
+    onCommit: (html: string) => void;
+    onSelect: () => void;
+}
+declare function RichText({ initialHtml, placeholder, variables, selected, inherited, onCommit, onSelect, }: RichTextProps): react.JSX.Element;
+
+declare const DEFAULT_BLOCKS: BlockDefinition[];
+
+declare function resolveEmailGlobal(global?: Partial<EmailGlobalSettings> | null): EmailGlobalSettings;
+declare function createEmailDocument(blocks?: EmailBlockNode[]): EmailDocument;
+
+declare function createBlockNode(type: string, definitions?: BlockDefinition[]): EmailBlockNode | null;
+
+declare const DIMENSION_FIELDS: {
+    padding: StyleFieldConfig;
+    margin: StyleFieldConfig;
+    height: StyleFieldConfig;
+};
+declare const DECORATION_FIELDS: {
+    backgroundColor: StyleFieldConfig;
+    borderWidth: StyleFieldConfig;
+    borderStyle: StyleFieldConfig;
+    borderColor: StyleFieldConfig;
+    borderRadius: StyleFieldConfig;
+};
+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;
+};
+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;
+
+interface BlockRenderOptions {
+    resolveHtmlTemplate?: boolean;
+    templateData?: TemplateData;
+    variables?: Variable[];
+    global?: EmailGlobalSettings;
+}
+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 buildRenderContext(node: EmailBlockNode, mode: RenderMode, global?: EmailGlobalSettings): BlockRenderContext;
+
+declare function getBlockDefinition(type: string, definitions?: BlockDefinition[]): BlockDefinition | undefined;
+
+declare function generateId(prefix?: string): string;
+
+interface StyleGroupOption {
+    group: StyleGroup;
+    label: string;
+}
+declare const STYLE_GROUPS: StyleGroupOption[];
+
+declare const BLOCK_TYPES: {
+    readonly heading: "heading";
+    readonly text: "text";
+    readonly button: "button";
+    readonly image: "image";
+    readonly divider: "divider";
+    readonly spacer: "spacer";
+    readonly html: "html";
+};
+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 };