dpk-editor 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { Extension, Extensions } from '@tiptap/react';
+
+/**
+ * Public types for dpk-editor.
+ *
+ * Kept in a dedicated module so both the components and the building-block
+ * utilities can import them without introducing circular dependencies, and so
+ * consumers get a single, stable surface to import from.
+ */
+/** Configuration for a single email-safe call-to-action button. */
+type EmailButtonConfig = {
+    /** Visible label of the button. */
+    text: string;
+    /** Destination URL. */
+    href: string;
+    /** Background color (any CSS color; used verbatim in the inline style). */
+    bgColor: string;
+    /** Text color (any CSS color; used verbatim in the inline style). */
+    textColor: string;
+    /** Horizontal alignment of the button within its block. */
+    align: "left" | "center" | "right";
+    /** Corner radius in pixels (typically 0–32). */
+    radius: number;
+    /** When true the anchor spans the full content width (block display). */
+    fullWidth: boolean;
+};
+/**
+ * A merge token (a.k.a. personalization placeholder) such as
+ * `{{FirstName}}`. Rendered as a chip in `<EmailEditor>` that inserts the
+ * raw token text at the caret when clicked.
+ */
+type EmailPlaceholder = {
+    /** The literal token inserted into the document, e.g. `{{FirstName}}`. */
+    token: string;
+    /** Human-readable label shown on the chip, e.g. "First name". */
+    label: string;
+};
+/** Per-button visibility within the inline-formatting group. */
+type InlineButtons = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    code?: boolean;
+};
+/** Per-button visibility within the headings group (H2–H6). */
+type HeadingButtons = {
+    h2?: boolean;
+    h3?: boolean;
+    h4?: boolean;
+    h5?: boolean;
+    h6?: boolean;
+};
+/** Per-button visibility within the lists group. */
+type ListButtons = {
+    bullet?: boolean;
+    ordered?: boolean;
+    blockquote?: boolean;
+};
+/** Per-button visibility within the text-align group. */
+type AlignButtons = {
+    left?: boolean;
+    center?: boolean;
+    right?: boolean;
+};
+/** Per-button visibility within the preset-blocks group. */
+type BlockButtons = {
+    paragraph?: boolean;
+    divider?: boolean;
+    footer?: boolean;
+};
+/**
+ * A group of buttons can be controlled two ways:
+ * - a `boolean` — show (`true`/omitted) or hide (`false`) the whole group;
+ * - an object of per-button booleans — show the group but override individual
+ *   buttons (each defaults to `true` when the group is shown).
+ *
+ * `true` and `{}` are equivalent (group on, all buttons on). `false` hides the
+ * whole group regardless of any per-button values.
+ */
+type ToolbarGroup<TButtons> = boolean | TButtons;
+/**
+ * Controls which toolbar controls render. Every key defaults to `true` (all
+ * controls visible).
+ *
+ * - Single-control groups (`link`, `image`, `button`, `html`) are plain
+ *   booleans: set to `false` to hide.
+ * - Multi-button groups (`inline`, `headings`, `lists`, `align`, `blocks`)
+ *   accept either a boolean (whole group) OR an object for per-button control,
+ *   e.g. `inline: { underline: false }` keeps Bold/Italic/Strike/Code but hides
+ *   Underline, while `inline: false` hides the entire inline group.
+ */
+type ToolbarConfig = {
+    /** Bold / Italic / Underline / Strikethrough / Inline code group. */
+    inline?: ToolbarGroup<InlineButtons>;
+    /** Heading level buttons (H2–H6). */
+    headings?: ToolbarGroup<HeadingButtons>;
+    /** Bullet list / Ordered list / Blockquote group. */
+    lists?: ToolbarGroup<ListButtons>;
+    /** Text-align left/center/right group. */
+    align?: ToolbarGroup<AlignButtons>;
+    /** Link control. */
+    link?: boolean;
+    /** Image control. */
+    image?: boolean;
+    /** Email CTA-button control (opens the button dialog). */
+    button?: boolean;
+    /** Preset block snippets group (Paragraph / Divider / Footer). */
+    blocks?: ToolbarGroup<BlockButtons>;
+    /** Raw HTML source toggle. */
+    html?: boolean;
+};
+/**
+ * The fully-resolved toolbar config used internally: every group is expanded to
+ * `{ enabled, buttons: {...all booleans} }`, so the Toolbar renders from a flat,
+ * non-optional shape. Produced by `resolveToolbarConfig`.
+ */
+type ResolvedToolbarConfig = {
+    inline: {
+        enabled: boolean;
+        buttons: Required<InlineButtons>;
+    };
+    headings: {
+        enabled: boolean;
+        buttons: Required<HeadingButtons>;
+    };
+    lists: {
+        enabled: boolean;
+        buttons: Required<ListButtons>;
+    };
+    align: {
+        enabled: boolean;
+        buttons: Required<AlignButtons>;
+    };
+    link: boolean;
+    image: boolean;
+    button: boolean;
+    blocks: {
+        enabled: boolean;
+        buttons: Required<BlockButtons>;
+    };
+    html: boolean;
+};
+/**
+ * The split representation of an email document. `prefix` is everything up to
+ * and including the opening `<body ...>` tag, `body` is the editable inner
+ * HTML, and `suffix` is `</body>` plus anything after it. For a bare fragment
+ * (no `<body>`), `prefix` and `suffix` are empty strings.
+ */
+type EmailHtmlDocument = {
+    prefix: string;
+    body: string;
+    suffix: string;
+};
+
+type EmailEditorProps = {
+    /** Full HTML document OR a bare body fragment — both are supported. */
+    value: string;
+    /** Fires with HTML in the same shape `value` was provided (shell re-applied). */
+    onChange: (value: string) => void;
+    /** Optional merge tokens; render a chip row that inserts at the caret. */
+    placeholders?: EmailPlaceholder[];
+    /** Resolve an uploaded file to a hosted image URL (else a URL prompt is used). */
+    onUploadImage?: (file: File) => Promise<string>;
+    /** Minimum height (px) of the editable surface. */
+    minHeight?: number;
+    /** Empty-state placeholder text for the editable surface. */
+    placeholder?: string;
+    /** Which toolbar controls to render (defaults to everything on). */
+    toolbar?: ToolbarConfig;
+    /** Extra class on the editor wrapper. */
+    className?: string;
+};
+/**
+ * The batteries-included email editor. Owns the document-shell bridge so the
+ * surrounding `<!doctype>`/`<html>`/`<body style>` (and any `<table>` layout
+ * inside the body) is preserved verbatim across edits, while only the body
+ * fragment is handed to the underlying `<RichTextEditor>`.
+ */
+declare function EmailEditor({ value, onChange, placeholders, onUploadImage, minHeight, placeholder, toolbar, className, }: EmailEditorProps): react_jsx_runtime.JSX.Element;
+
+type RichTextEditorHandle = {
+    /** Insert raw HTML or plain text at the current caret position. */
+    insertAtCaret: (htmlOrText: string) => void;
+};
+type RichTextEditorProps = {
+    /** Body-level HTML fragment (no `<html>`/`<body>`). */
+    value: string;
+    /** Fires with the updated body-level HTML fragment. */
+    onChange: (value: string) => void;
+    /** Empty-state placeholder text. */
+    placeholder?: string;
+    /** Resolve an uploaded file to a hosted image URL. */
+    onUploadImage?: (file: File) => Promise<string>;
+    /** Extra class on the editor wrapper. */
+    className?: string;
+    /** Inline style applied to the editable surface (e.g. minHeight/height). */
+    editorStyle?: React.CSSProperties;
+    /** Which toolbar controls to render (defaults to everything on). */
+    toolbar?: ToolbarConfig;
+};
+/**
+ * The generic body-HTML rich-text editor: a toolbar plus an editable surface
+ * operating on a plain HTML fragment. `<EmailEditor>` wraps this to add the
+ * document-shell bridge and placeholder chips.
+ */
+declare const RichTextEditor: react.ForwardRefExoticComponent<RichTextEditorProps & react.RefAttributes<RichTextEditorHandle>>;
+
+type EmailButtonDialogProps = {
+    /** Whether the dialog is open. */
+    open: boolean;
+    /** Called when the user confirms; receives the email-safe button HTML. */
+    onConfirm: (html: string, config: EmailButtonConfig) => void;
+    /** Called when the user dismisses the dialog (Esc / click-outside / cancel). */
+    onClose: () => void;
+    /** Optional initial values for the form. */
+    initial?: Partial<EmailButtonConfig>;
+};
+/**
+ * Modal dialog for configuring an email CTA button. Supports Esc to close,
+ * body-scroll lock while open, click-outside to dismiss, and a live preview of
+ * the rendered button.
+ */
+declare function EmailButtonDialog({ open, onConfirm, onClose, initial, }: EmailButtonDialogProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * A TipTap extension that preserves the inline `style` attribute on every node
+ * and mark in the schema.
+ *
+ * TipTap (ProseMirror) strips any HTML attribute a node/mark does not declare.
+ * For article editing that is fine; for **email** HTML it is lossy — buttons
+ * lose their padding/background, headings lose their color, and so on. This
+ * extension declares a global `style` attribute so arbitrary inline-styled
+ * email HTML round-trips.
+ *
+ * It preserves `style` only on elements that map to a known node or mark
+ * (paragraph, heading, list, blockquote, link, image, hr, …). Raw
+ * `<table>`/`<td>` layouts are still flattened by ProseMirror's schema — those
+ * survive via the document-shell bridge, not here.
+ */
+declare const PreserveStyles: Extension<any, any>;
+
+/**
+ * The canonical extension set for the email editor.
+ *
+ * Notes / watch-outs baked in here:
+ * - StarterKit v3 already bundles Link, Underline, lists, blockquote, code and
+ *   headings — we do NOT add @tiptap/extension-link or -underline separately
+ *   (that throws duplicate-extension warnings). Link is configured through
+ *   StarterKit.configure({ link: {...} }).
+ * - Image is block-level and base64 is disabled (uploads should resolve to a
+ *   hosted URL, which is what email clients can render).
+ * - PreserveStyles must be present so inline `style` survives the round-trip.
+ * - Placeholder is NOT bundled by StarterKit v3, so it is added explicitly to
+ *   power the empty-state hint (it sets the `is-editor-empty` class and the
+ *   `data-placeholder` attribute that styles.css renders via `::before`).
+ *
+ * Exported as a factory so the React component and the headless tests build an
+ * identical extension set. Pass the empty-state placeholder text in.
+ */
+declare function createEmailExtensions(placeholder?: string): Extensions;
+
+/**
+ * Build email-safe HTML for a call-to-action button.
+ *
+ * Two non-obvious decisions, both load-bearing:
+ *
+ * 1. The anchor is wrapped in a `<p style="...;text-align:X">`, **never** a
+ *    `<div>`. TipTap has no `div` node and unwraps a `<div>` into a paragraph,
+ *    losing the `text-align`. A paragraph is a real node whose `text-align`
+ *    the TextAlign extension preserves — so the alignment round-trips.
+ *
+ * 2. The button is an `<a style="display:inline-block;...">` (or
+ *    `display:block` when full-width), not a `<button>`, because email clients
+ *    need bulletproof, inline-styled markup.
+ *
+ * Both the label and the href are HTML-escaped.
+ */
+declare function buildButtonHtml(config: EmailButtonConfig): string;
+
+/**
+ * Escape a string for safe insertion into HTML text or a double-quoted
+ * attribute value. Used by `buildButtonHtml` for the button label and href.
+ */
+declare function escapeHtml(value: string): string;
+
+/**
+ * Split a full email HTML document into `{ prefix, body, suffix }`.
+ *
+ * - `prefix` = everything up to and including the opening `<body ...>` tag.
+ * - `body`   = the inner body HTML (the editable fragment).
+ * - `suffix` = the closing `</body>` tag plus everything after it.
+ *
+ * If the input has no `<body>` tag it is treated as a **bare fragment**: the
+ * whole input becomes `body`, and `prefix`/`suffix` are empty strings.
+ */
+declare function splitEmailHtml(html: string): EmailHtmlDocument;
+/**
+ * Reassemble a document from a shell and a (possibly edited) body fragment.
+ *
+ * If the shell has no surrounding markup (a bare fragment was originally
+ * supplied) the body is returned as-is, so `onChange` emits in the same shape
+ * the consumer provided `value`.
+ */
+declare function joinEmailHtml(shell: EmailHtmlDocument, newBody: string): string;
+/**
+ * Convenience: extract just the editable body fragment from a full document
+ * (or return the input unchanged if it is already a bare fragment).
+ */
+declare function extractEmailBody(html: string): string;
+
+/**
+ * Preset block snippets — small, inline-styled, email-safe HTML fragments
+ * inserted at the caret via `editor.chain().focus().insertContent(snippet)`.
+ *
+ * Every snippet uses inline styles only (no classes) so it survives both the
+ * editor schema (via PreserveStyles) and downstream email clients.
+ */
+declare const PRESET_PARAGRAPH = "<p style=\"margin:0 0 12px;color:#4b5563;line-height:1.6;\">Write your message here.</p>";
+declare const PRESET_DIVIDER = "<hr style=\"border:none;border-top:1px solid #e5e7eb;margin:20px 0;\" />";
+declare const PRESET_FOOTER = "<p style=\"margin:20px 0 0;color:#9ca3af;font-size:12px;\">\u00A9 Your Company</p>";
+declare const PRESET_HEADING = "<h2 style=\"margin:0 0 12px;color:#111827;font-size:24px;line-height:1.3;\">Heading</h2>";
+declare const presets: {
+    readonly paragraph: "<p style=\"margin:0 0 12px;color:#4b5563;line-height:1.6;\">Write your message here.</p>";
+    readonly divider: "<hr style=\"border:none;border-top:1px solid #e5e7eb;margin:20px 0;\" />";
+    readonly footer: "<p style=\"margin:20px 0 0;color:#9ca3af;font-size:12px;\">© Your Company</p>";
+    readonly heading: "<h2 style=\"margin:0 0 12px;color:#111827;font-size:24px;line-height:1.3;\">Heading</h2>";
+};
+
+declare function resolveToolbarConfig(config?: ToolbarConfig): ResolvedToolbarConfig;
+
+export { type AlignButtons, type BlockButtons, type EmailButtonConfig, EmailButtonDialog, type EmailButtonDialogProps, EmailEditor, type EmailEditorProps, type EmailHtmlDocument, type EmailPlaceholder, type HeadingButtons, type InlineButtons, type ListButtons, PRESET_DIVIDER, PRESET_FOOTER, PRESET_HEADING, PRESET_PARAGRAPH, PreserveStyles, type ResolvedToolbarConfig, RichTextEditor, type RichTextEditorHandle, type RichTextEditorProps, type ToolbarConfig, type ToolbarGroup, buildButtonHtml, createEmailExtensions, EmailEditor as default, escapeHtml, extractEmailBody, joinEmailHtml, presets, resolveToolbarConfig, splitEmailHtml };