@maildeno/editor 0.1.0

package/dist/init.d.ts

@@ -0,0 +1,85 @@
+import { PartialStorageAdapter } from './adapters/types';
+import { ThemeOptions } from './theme';
+/**
+ * The ergonomic, no-Vue-knowledge entry point. element.ts already provides
+ * everything this composes — a real custom element, complete CSS bundling,
+ * live theming via CSS variables — init() just wires it up with a plain
+ * options object and hands back a small handle instead of requiring the
+ * caller to know defineCustomElement, prop reflection, or DOM CustomEvent
+ * details themselves.
+ */
+export interface InitOptions {
+    /** A DOM element, or a CSS selector resolved via document.querySelector. */
+    container: HTMLElement | string;
+    templateId?: string;
+    storageAdapter?: PartialStorageAdapter;
+    theme?: ThemeOptions;
+    capabilities?: {
+        export?: Array<"html" | "mjml" | "react" | "json">;
+    };
+    onSendTestEmail?: (payload: {
+        to: string;
+        subject: string;
+        html: string;
+    }) => Promise<void> | void;
+    /**
+     * Render inside a shadow root (default) or directly in the page.
+     *
+     * Shadow DOM isolates the editor's styles from the host page, which is
+     * usually what you want. Set false when you'd rather have predictable
+     * DOM behaviour than isolation: inside a shadow root `event.target` is
+     * retargeted to the host, `document.activeElement` returns the host,
+     * `document.querySelector` can't see in, and `@font-face`/`@property`
+     * are ignored. This package handles all of that internally, but a host
+     * page's own scripts — or a third-party library — may not, and that is
+     * not fixable from inside the editor. Light DOM is the escape hatch.
+     *
+     * The trade-off is real in both directions: with `shadowDom: false`,
+     * the host page's CSS can reach the editor and vice versa.
+     */
+    shadowDom?: boolean;
+}
+export interface EditorHandle {
+    /** The underlying <maildeno-editor> element, for anything this handle
+     * doesn't wrap directly — it's a real DOM element, nothing hidden. */
+    readonly element: HTMLElement;
+    /** Vue's defineCustomElement dispatches emits as real DOM CustomEvents
+     * on the host element, with the emit payload in event.detail — this is
+     * just addEventListener with that unwrapping done for you. */
+    on(event: "save", handler: (payload: {
+        templateId: string | null;
+    }) => void): void;
+    off(event: "save", handler: (payload: {
+        templateId: string | null;
+    }) => void): void;
+    /** Re-themes live — sets the theme prop, which EmailEditor.vue's own
+     * watch(..., {immediate: true}) picks up via useHost(), the same
+     * mechanism that applies it on initial mount. Calling this again after
+     * mount is the actual "live" part, not just initial configuration. */
+    setTheme(theme: ThemeOptions): void;
+    /** These four call EmailEditor.vue's defineExpose'd methods, which Vue's
+     * own defineCustomElement implementation forwards directly onto the
+     * custom element instance (confirmed: _instance.exposed is read and
+     * redefined as properties on the element itself, not something Vue-
+     * internal or requiring a $refs-style lookup). "prune" (default)
+     * evaluates against the current preview context; "wrap" always
+     * includes every ESP-conditional branch, matching the same two modes
+     * the Export dropdown itself offers. */
+    getHtml(mode?: "prune" | "wrap"): string | null;
+    getMjml(mode?: "prune" | "wrap"): string | null;
+    getReactEmail(mode?: "prune" | "wrap"): string | null;
+    getJson(): Record<string, unknown> | null;
+    /** Removes the element from the DOM. Vue's custom element wrapper
+     * handles unmounting the internal app and cleaning up watchers/effects
+     * as part of its own disconnectedCallback — not reimplemented here. */
+    destroy(): void;
+}
+export declare function init(options: InitOptions): Promise<EditorHandle>;
+export { registerBlock, getBlock, getAllBlocks, } from './blocks/registry';
+export { registerESPSyntax, getRegisteredCustomESPs, } from './esp/registry';
+export { registerMergeTags, getRegisteredMergeTagIds, } from './merge-tags/registry';
+export { setEditorTheme, palette } from './theme';
+export { createLocalStorageAdapter } from './adapters/localStorageAdapter';
+export type { BlockDefinition } from './blocks/types';
+export type { ThemeOptions, ThemeTokens } from './theme';
+export type { EditorStorageAdapter, PartialStorageAdapter, TemplateSnapshot, TemplateSummary, SavedRow, } from './adapters/types';

package/dist/init.js

@@ -0,0 +1,130 @@
+import { D as h, at as ref, i as createApp, rt as reactive } from "./vue.runtime.esm-bundler-DwQEK7WO.js";
+import { a as setEditorTheme, c as createLocalStorageAdapter, d as getRegisteredMergeTagIds, f as registerMergeTags, h as registerBlock, i as palette, l as getRegisteredCustomESPs, m as getBlock, n as registerMaildenoEditorElement, p as getAllBlocks, r as EmailEditor_default, s as buildShadowStyles, u as registerESPSyntax } from "./element-DN22fZmQ.js";
+//#region src/lightDom.ts
+var stylesInjected = false;
+/**
+* The shadow path hands these strings to defineCustomElement, which turns
+* them into <style> tags inside the shadow root. Here they go to
+* document.head instead — same content, different destination. Guarded so
+* multiple editors on one page inject once.
+*/
+function injectStylesIntoHead() {
+	if (stylesInjected || typeof document === "undefined") return;
+	stylesInjected = true;
+	for (const css of buildShadowStyles()) {
+		if (!css) continue;
+		const style = document.createElement("style");
+		style.setAttribute("data-maildeno-light-dom", "");
+		style.textContent = css;
+		document.head.appendChild(style);
+	}
+}
+function mountLightDom(container, initialProps) {
+	injectStylesIntoHead();
+	const props = reactive({ ...initialProps });
+	const saveHandlers = /* @__PURE__ */ new Set();
+	const editorRef = ref(null);
+	const mountEl = document.createElement("div");
+	mountEl.style.height = "100%";
+	container.appendChild(mountEl);
+	const app = createApp({ setup() {
+		return () => h(EmailEditor_default, {
+			...props,
+			ref: editorRef,
+			onSave: (payload) => saveHandlers.forEach((fn) => fn(payload))
+		});
+	} });
+	app.mount(mountEl);
+	return {
+		element: mountEl,
+		exposed: () => editorRef.value ?? null,
+		setProp: (key, value) => {
+			props[key] = value;
+		},
+		addSaveHandler: (fn) => saveHandlers.add(fn),
+		removeSaveHandler: (fn) => saveHandlers.delete(fn),
+		destroy: () => {
+			app.unmount();
+			mountEl.remove();
+		}
+	};
+}
+//#endregion
+//#region src/init.ts
+function toDomEventName(event) {
+	return event;
+}
+async function init(options) {
+	const container = typeof options.container === "string" ? document.querySelector(options.container) : options.container;
+	if (!container) throw new Error(`[maildeno-editor] init() couldn't find a container${typeof options.container === "string" ? ` matching "${options.container}"` : ""}.`);
+	if (options.shadowDom === false) {
+		const mount = mountLightDom(container, {
+			templateId: options.templateId,
+			storageAdapter: options.storageAdapter,
+			theme: options.theme,
+			capabilities: options.capabilities,
+			onSendTestEmail: options.onSendTestEmail
+		});
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		const call = (name, ...args) => {
+			const fn = mount.exposed()?.[name];
+			return typeof fn === "function" ? fn(...args) : null;
+		};
+		return {
+			element: mount.element,
+			on: (_event, handler) => mount.addSaveHandler(handler),
+			off: (_event, handler) => mount.removeSaveHandler(handler),
+			setTheme: (theme) => mount.setProp("theme", theme),
+			getHtml: (mode = "prune") => call("getHtml", mode),
+			getMjml: (mode = "prune") => call("getMjml", mode),
+			getReactEmail: (mode = "prune") => call("getReactEmail", mode),
+			getJson: () => call("getJson"),
+			destroy: () => mount.destroy()
+		};
+	}
+	registerMaildenoEditorElement();
+	const el = document.createElement("maildeno-editor");
+	if (options.templateId !== void 0) el.templateId = options.templateId;
+	if (options.storageAdapter) el.storageAdapter = options.storageAdapter;
+	if (options.theme) el.theme = options.theme;
+	if (options.capabilities) el.capabilities = options.capabilities;
+	if (options.onSendTestEmail) el.onSendTestEmail = options.onSendTestEmail;
+	container.appendChild(el);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const listenerWrappers = /* @__PURE__ */ new WeakMap();
+	return {
+		element: el,
+		on(event, handler) {
+			const wrapped = ((e) => handler(Array.isArray(e.detail) ? e.detail[0] : e.detail));
+			listenerWrappers.set(handler, wrapped);
+			el.addEventListener(toDomEventName(event), wrapped);
+		},
+		off(event, handler) {
+			const wrapped = listenerWrappers.get(handler);
+			if (wrapped) {
+				el.removeEventListener(toDomEventName(event), wrapped);
+				listenerWrappers.delete(handler);
+			}
+		},
+		setTheme(theme) {
+			el.theme = theme;
+		},
+		getHtml(mode = "prune") {
+			return el.getHtml ? el.getHtml(mode) : null;
+		},
+		getMjml(mode = "prune") {
+			return el.getMjml ? el.getMjml(mode) : null;
+		},
+		getReactEmail(mode = "prune") {
+			return el.getReactEmail ? el.getReactEmail(mode) : null;
+		},
+		getJson() {
+			return el.getJson ? el.getJson() : null;
+		},
+		destroy() {
+			el.remove();
+		}
+	};
+}
+//#endregion
+export { createLocalStorageAdapter, getAllBlocks, getBlock, getRegisteredCustomESPs, getRegisteredMergeTagIds, init, palette, registerBlock, registerESPSyntax, registerMergeTags, setEditorTheme };

package/dist/lightDom.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Mounts the editor directly into the page, with no shadow root.
+ *
+ * This is the `shadowDom: false` path. Shadow DOM buys style isolation,
+ * but it costs real behaviour: `event.target` is retargeted to the host,
+ * `document.activeElement` returns the host rather than the focused
+ * element, `document.querySelector` cannot see inside, and `@font-face`
+ * and `@property` are ignored entirely. Every one of those has caused a
+ * concrete bug in this package, and third-party libraries hit them too —
+ * Reka UI's own internals use `document.activeElement` and never
+ * `composedPath()`, so anything built on it can misbehave inside a shadow
+ * root in ways that cannot be fixed from the outside.
+ *
+ * Light DOM trades isolation for predictability: the host page's CSS can
+ * reach the editor (and vice versa), but every browser API behaves
+ * normally. It is the right choice when the host page's styles are known
+ * and controlled, and the escape hatch when something in the shadow path
+ * misbehaves.
+ */
+export interface LightDomMount {
+    /** The element the editor was mounted into. */
+    element: HTMLElement;
+    /** Reads EmailEditor.vue's defineExpose'd methods. */
+    exposed: () => Record<string, any> | null;
+    setProp: (key: string, value: unknown) => void;
+    addSaveHandler: (fn: (payload: any) => void) => void;
+    removeSaveHandler: (fn: (payload: any) => void) => void;
+    destroy: () => void;
+}
+export declare function mountLightDom(container: HTMLElement, initialProps: Record<string, unknown>): LightDomMount;

package/dist/merge-tags/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Confirmed against the real pipeline (mergeTagMapper.ts's transformToken):
+ * any tag ID not in the hardcoded SYSTEM_TAG_MAP already falls through to
+ * transformCustomTag, which handles arbitrary tag names generically for
+ * all known ESP syntaxes — this was already true before this registry
+ * existed (see the "Zero Vendor Lock-in" note in mergeTagMapper.ts).
+ *
+ * So registering a merge tag isn't fixing a correctness gap the way the
+ * ESP registry was. It solves a narrower, real problem: getSystemTagIds()
+ * only returns SYSTEM_TAG_MAP's hardcoded keys, so a host's own fields
+ * (order_total, loyalty_points, ...) never show up in the "Common tags"
+ * picker UI — a user would have to already know to type {{ order_total }}
+ * by hand. This registry makes registered tags discoverable there.
+ *
+ * Optional per-ESP token overrides exist for the rare case a custom tag
+ * needs something other than the generic transform (e.g. a genuinely
+ * ESP-specific system-level token) — most registrations won't need them.
+ */
+export interface MergeTagRegistration {
+    key: string;
+    /** Optional — omit to use the existing generic transformCustomTag path
+     * for every ESP syntax, which is already correct for ordinary data
+     * fields. Only provide this for a tag that needs ESP-specific hardcoded
+     * tokens, the same category SYSTEM_TAG_MAP covers for built-ins. */
+    tokens?: Partial<Record<string, string>>;
+}
+export declare function registerMergeTags(tags: MergeTagRegistration[]): void;
+/** Custom-registered IDs, appended after the built-ins for the picker UI. */
+export declare function getRegisteredMergeTagIds(): string[];
+/** Only returns a value for tags that were registered WITH explicit token
+ * overrides — most registered tags return undefined here on purpose, so
+ * transformToken's existing transformCustomTag fallback handles them. */
+export declare function getRegisteredMergeTagToken(tagId: string, syntax: string): string | undefined;

package/dist/shadowStyles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * False when running from source, where the build-time substitution above
+ * never ran and the shadow root therefore has no component CSS. Used to
+ * decide whether the dev style mirror is needed — a capability check rather
+ * than an environment guess, so it self-corrects in either direction.
+ */
+export declare function hasExtractedScopedCss(): boolean;
+export declare function buildShadowStyles(): string[];