@servicetitan/dte-unlayer 0.152.0 → 0.154.0

package/src/store.ts

@@ -1,4 +1,6 @@
 import { loadScript } from './loadScript';
+import { logUnlayerError } from './log';
+import { toUnlayerMergeTags, type UnlayerMergeTagsConfig } from './merge-tags';
 import { defaultImageValidation } from './shared/configs';
 import type { UnlayerEditorTwin, UnlayerEventConfig, UnlayerEventRegister } from './shared/const';
 import { unlayerSupportedFonts } from './shared/fonts';
@@ -10,16 +12,22 @@ import {
 } from './shared/forms';
 import { schemaBuildMap, schemaIsDate } from './shared/schema';
 import { unlayerToolsParseTwinKey } from './shared/tools';
-import { unlayerToolsIterate } from './tools';
+import { unlayerToolsDedupeInstanceIds, unlayerToolsIterate } from './tools';
 import {
     createUnlayerEditor,
     DesignUpdatedEventType,
     EventDesignUpdated,
     Unlayer,
 } from './unlayer';
-import { CreateUnlayerEditorProps, UnlayerDesignFormat, UnlayerRef } from './unlayer-interface';
+import {
+    CreateUnlayerEditorProps,
+    UnlayerDesignFormat,
+    UnlayerEditorMergeTagInfo,
+    UnlayerRef,
+} from './unlayer-interface';
 
 const defaultScriptUrl = 'https://editor.unlayer.com/embed.js?2';
+const UNLAYER_TOOLS_READY_TIMEOUT_MS = 30000;
 
 const normalizeFontToken = (font: string) =>
     font.replace(/["']/g, '').split(',')[0].trim().toLowerCase();
@@ -184,8 +192,14 @@ export class UnlayerStore {
     private isInit = false;
     private iframe?: HTMLIFrameElement;
     private hasDesign = false;
+    private hasCoreLoaded = false;
+    private hasToolsRegistered = false;
+    private toolsReadyWatchdogId?: number;
     private formFieldsByFormId: Record<number, FormFieldInfo[]> = {};
     private formFieldSamples: Record<string, unknown> = {};
+    private isEditorReady = false;
+    private isMergeTagsApplied = false;
+    private mergeTagsConfig?: UnlayerMergeTagsConfig;
 
     private onMessageCB?: (type: string, data: any) => void;
     private onChangeCB?: (info: UnlayerDesignChangeInfo) => void;
@@ -231,6 +245,9 @@ export class UnlayerStore {
             sendCalcFieldLabels: labels => {
                 this.sendCalcFieldLabels(labels);
             },
+            setMergeTags: tags => {
+                this.setMergeTags(tags);
+            },
         };
     }
 
@@ -241,22 +258,44 @@ export class UnlayerStore {
 
         this.isInit = true;
 
-        setTimeout(() => window.addEventListener('message', this.onPostMessage));
+        try {
+            setTimeout(() => window.addEventListener('message', this.onPostMessage));
+
+            await loadScript(defaultScriptUrl);
+
+            if (!(window as any).unlayer) {
+                throw new Error('Unlayer embed script loaded but window.unlayer is missing');
+            }
+
+            this.editor = createUnlayerEditor(container, this.props);
+            // The host may already have pushed a newer set through `setMergeTags`; keep it.
+            this.mergeTagsConfig ??= toUnlayerMergeTags(this.props.mergeTags);
+            this.editor.addEventListener('editor:ready', this.onEditorReady);
+            this.editor.addEventListener('design:loaded', this.onDesignLoaded);
+            this.editor.addEventListener('design:updated', this.onDesignUpdated);
+            this.editor.registerCallback('image', this.uploadImage);
 
-        await loadScript(defaultScriptUrl);
+            this.iframe = container.querySelector(`iframe`) ?? undefined;
 
-        this.editor = createUnlayerEditor(container, this.props);
-        this.editor.addEventListener('design:loaded', this.onDesignLoaded);
-        this.editor.addEventListener('design:updated', this.onDesignUpdated);
-        this.editor.registerCallback('image', this.uploadImage);
+            if (!this.iframe) {
+                logUnlayerError('Unlayer iframe was not created after createEditor');
+            }
 
-        this.iframe = container.querySelector(`iframe`) ?? undefined;
+            this.startToolsReadyWatchdog();
+        } catch (error: unknown) {
+            this.isInit = false;
+            this.clearToolsReadyWatchdog();
+            logUnlayerError('Failed to initialize Unlayer editor', error);
+            throw error;
+        }
     };
 
     destroy = () => {
+        this.clearToolsReadyWatchdog();
         window.removeEventListener('message', this.onPostMessage);
 
         if (this.editor) {
+            this.editor.removeEventListener('editor:ready', this.onEditorReady);
             this.editor.removeEventListener('design:loaded', this.onDesignLoaded);
             this.editor.removeEventListener('design:updated', this.onDesignUpdated);
             this.editor.unregisterCallback('image', this.uploadImage);
@@ -332,7 +371,46 @@ export class UnlayerStore {
         this.sendMessage('--calc-field-labels', { labels });
     };
 
+    /**
+     * Replaces the editor's merge tag menu. Nested groups passed to `createEditor` stop DTE
+     * custom tools from registering, so init only carries the flat shape and the grouped
+     * config is applied here once the editor is ready. A call before that (including the
+     * initial props) is parked; a later call replaces it. A failed apply is retried on the
+     * next `design:loaded`.
+     */
+    setMergeTags = (tags: UnlayerEditorMergeTagInfo[] | undefined) => {
+        this.mergeTagsConfig = toUnlayerMergeTags(tags);
+        this.isMergeTagsApplied = false;
+        this.applyMergeTags();
+    };
+
+    private applyMergeTags = () => {
+        if (
+            !this.editor ||
+            !this.isEditorReady ||
+            this.isMergeTagsApplied ||
+            !this.mergeTagsConfig
+        ) {
+            return;
+        }
+
+        try {
+            this.editor.setMergeTags(this.mergeTagsConfig);
+            this.isMergeTagsApplied = true;
+        } catch (error: unknown) {
+            logUnlayerError('Failed to apply merge tags', error);
+        }
+    };
+
+    private onEditorReady = () => {
+        this.isEditorReady = true;
+        this.applyMergeTags();
+    };
+
     private onDesignLoaded = () => {
+        // A loaded design means the editor is up even if `editor:ready` never reached us.
+        this.onEditorReady();
+
         if (!this.hasDesign) {
             this.hasDesign = true;
             this.editor?.setBodyValues({
@@ -368,6 +446,11 @@ export class UnlayerStore {
                     }
                 });
 
+                // Duplicated contents/rows carry the original's instance GUIDs; give copies new ones.
+                if (unlayerToolsDedupeInstanceIds(data.design, event.item?.values?._meta?.htmlID)) {
+                    hasChanges = true;
+                }
+
                 if (hasChanges) {
                     this.setDesign(data.design);
                 }
@@ -392,8 +475,11 @@ export class UnlayerStore {
         }
 
         if (type === '--ready' || type === '--registered') {
+            this.hasToolsRegistered = true;
+            this.clearToolsReadyWatchdog();
             this.onReadyCB?.();
         } else if (type === '--core-loaded') {
+            this.hasCoreLoaded = true;
             const configData: UnlayerEventConfig = {
                 dummyData: this.props.dummyData,
                 schema: this.props.schema,
@@ -588,6 +674,7 @@ export class UnlayerStore {
         });
 
         if (!res.isValid) {
+            logUnlayerError(`Image validation failed: ${res.title}`, res.description);
             this.onErrorCB?.(res.title, res.description);
             return;
         }
@@ -597,7 +684,8 @@ export class UnlayerStore {
         try {
             const { url } = await this.onImageCB(file);
             done({ progress: 100, url });
-        } catch {
+        } catch (error: unknown) {
+            logUnlayerError('Image upload failed', error);
             this.onErrorCB?.(
                 'Image upload failed',
                 'Something went wrong while uploading the image. Please try again or select another image.',
@@ -606,6 +694,36 @@ export class UnlayerStore {
         }
     };
 
+    private startToolsReadyWatchdog = () => {
+        this.clearToolsReadyWatchdog();
+        this.toolsReadyWatchdogId = window.setTimeout(() => {
+            if (this.hasToolsRegistered) {
+                return;
+            }
+
+            logUnlayerError(
+                'Unlayer custom tools did not finish loading. customJS may not have run, or tool registration stalled.',
+                {
+                    hasCoreLoaded: this.hasCoreLoaded,
+                    hasToolsRegistered: this.hasToolsRegistered,
+                },
+            );
+            this.onErrorCB?.(
+                'Editor failed to load custom tools',
+                'Unlayer custom tools did not finish loading. Check the browser console for [dte-unlayer] details.',
+            );
+        }, UNLAYER_TOOLS_READY_TIMEOUT_MS);
+    };
+
+    private clearToolsReadyWatchdog = () => {
+        if (this.toolsReadyWatchdogId === undefined) {
+            return;
+        }
+
+        window.clearTimeout(this.toolsReadyWatchdogId);
+        this.toolsReadyWatchdogId = undefined;
+    };
+
     private validateImage = async (
         file: File,
         imageValidation: { maxFileSize: number; maxWidth: number; maxHeight: number },

package/src/tools.ts

@@ -1,5 +1,6 @@
 import { constGenericsEditor, UnlayerToolMetaData } from './shared/const';
 import { editIconSvg } from './shared/edit-icon';
+import { generateInstanceId, INSTANCE_ID_TOOL_SLUGS } from './shared/instance-id';
 import { unlayerToolsParseUnitKey } from './shared/tools';
 import { versions } from './unlayer';
 
@@ -202,6 +203,56 @@ export const unlayerToolsListCustom = (design: UnlayerDesignFormat): UnlayerDesi
     return tools;
 };
 
+/**
+ * Makes `values.id` unique across all instance-id tools (see `INSTANCE_ID_TOOL_SLUGS`)
+ * in the design. Duplicating content/rows in Unlayer copies the values verbatim, so
+ * every copy ends up with the original's GUID; this gives each copy a fresh one.
+ *
+ * Of the contents sharing an id, the one that keeps it is the first in document
+ * order that is not the just-added content (`addedHtmlID`), so the original always
+ * wins over its duplicate regardless of where the copy was inserted.
+ *
+ * @returns `true` when at least one id was regenerated.
+ */
+export const unlayerToolsDedupeInstanceIds = (
+    design: UnlayerDesignFormat,
+    addedHtmlID?: string
+): boolean => {
+    const byId = new Map<string, UnlayerDesignCustomTool[]>();
+
+    unlayerToolsIterateCustom(design, tool => {
+        const id = tool.values?.id;
+
+        if (INSTANCE_ID_TOOL_SLUGS.includes(tool.slug) && typeof id === 'string' && id) {
+            const key = `${tool.slug}|${id}`;
+            byId.set(key, [...(byId.get(key) ?? []), tool]);
+        }
+    });
+
+    let hasChanges = false;
+
+    byId.forEach(tools => {
+        if (tools.length < 2) {
+            return;
+        }
+
+        const keeper = tools.find(tool => tool.values?._meta?.htmlID !== addedHtmlID) ?? tools[0];
+
+        for (const tool of tools) {
+            if (tool !== keeper) {
+                /*
+                 * If no id can be generated the copy is left without one, which is still
+                 * better than two instances bound to the same image.
+                 */
+                tool.values.id = generateInstanceId();
+                hasChanges = true;
+            }
+        }
+    });
+
+    return hasChanges;
+};
+
 export const unlayerToolsBuildDesign = (tools: UnlayerDesignTool[]): UnlayerDesignFormat => {
     const design = unlayerGetDefaultDesign();
 

package/src/unlayer-interface.tsx

@@ -45,13 +45,23 @@ export interface UnlayerRef {
     sendFormList(forms: FormInfo[]): void;
     sendFormFields(formId: number, fields: FormFieldInfo[]): void;
     sendCalcFieldLabels(labels: Record<string, string>): void;
+    /**
+     * Replaces the editor's merge tag menu with `tags` (grouped). Safe to call before the editor is
+     * ready — the tags are applied once it is. Lets hosts add tags that finish loading after init
+     * (e.g. form fields) without remounting the editor.
+     */
+    setMergeTags(tags: UnlayerEditorMergeTagInfo[] | undefined): void;
 }
 
 export interface UnlayerEditorMergeTagInfo {
     id: string;
     name: string;
     propertyPath: string;
-    group?: string;
+    /**
+     * Submenu the tag is listed under. A string is a single submenu (`'Custom Fields'`);
+     * an array nests submenus in order (`['Forms', 'Customer Intake']` → Forms ▸ Customer Intake ▸ tag).
+     */
+    group?: string | string[];
 }
 
 export interface UnlayerEditorCustomTool {

package/src/unlayer.tsx

@@ -1,5 +1,6 @@
 import { emitDisplayCondition } from './display-conditions/displayConditionController';
 import { editorCoreScript, editorCoreStyles, editorCoreTools } from './editor-core';
+import { logUnlayerError } from './log';
 import { toUnlayerMergeTags } from './merge-tags';
 import { constGenericsEditor } from './shared/const';
 import { unlayerSupportedFonts } from './shared/fonts';
@@ -276,75 +277,94 @@ export const createUnlayerEditor = (
         },
     };
 
-    const result = (window as any).unlayer.createEditor({
-        displayMode: 'web',
-        devices: ['desktop'],
-        features: {
-            preview: true,
-            userUploads: false,
-            stockImages: false,
-            textEditor: {
-                tables: true,
+    let result: Unlayer;
+
+    try {
+        const unlayerApi = (window as any).unlayer;
+
+        if (!unlayerApi?.createEditor) {
+            throw new Error(
+                'Unlayer embed is not available. window.unlayer.createEditor is missing.',
+            );
+        }
+
+        result = unlayerApi.createEditor({
+            displayMode: 'web',
+            devices: ['desktop'],
+            features: {
+                preview: true,
+                userUploads: false,
+                stockImages: false,
+                textEditor: {
+                    tables: true,
+                },
             },
-        },
-        mergeTags: toUnlayerMergeTags(mergeTags),
-        projectId: 5713,
-        version: latest ? undefined : versions.unlayer,
-        appearance: {
-            theme: 'classic_light',
-        },
-        tools: {
-            'carousel': { enabled: false },
-            'button': { enabled: false },
-            'html': {
-                enabled: enableHTMLEditing,
-                properties: {
-                    html: {
-                        editor: {
-                            widgetParams: {
-                                codeMirrorOptions: {
-                                    readOnly: enableHTMLEditingReadonly,
+            /*
+             * Flat only: nested groups here break custom tool registration. UnlayerStore applies
+             * the grouped config via setMergeTags once the editor is ready.
+             */
+            mergeTags: toUnlayerMergeTags(mergeTags, { groups: false }),
+            projectId: 5713,
+            version: latest ? undefined : versions.unlayer,
+            appearance: {
+                theme: 'classic_light',
+            },
+            tools: {
+                'carousel': { enabled: false },
+                'button': { enabled: false },
+                'html': {
+                    enabled: enableHTMLEditing,
+                    properties: {
+                        html: {
+                            editor: {
+                                widgetParams: {
+                                    codeMirrorOptions: {
+                                        readOnly: enableHTMLEditingReadonly,
+                                    },
                                 },
                             },
                         },
                     },
                 },
+                'table': {
+                    enabled: true,
+                },
+                'menu': { enabled: false },
+                'form': { enabled: false },
+                ...(noCoreTools
+                    ? {
+                          columns: { enabled: false },
+                          text: { enabled: false },
+                          heading: { enabled: false },
+                          divider: { enabled: false },
+                          image: { enabled: false },
+                      }
+                    : {}),
+                ...unitsConfig,
+                'custom#e-sign': eSignComponentRecipients,
             },
-            'table': {
-                enabled: true,
+            editor: {
+                autoSelectOnDrop: true,
             },
-            'menu': { enabled: false },
-            'form': { enabled: false },
-            ...(noCoreTools
-                ? {
-                      columns: { enabled: false },
-                      text: { enabled: false },
-                      heading: { enabled: false },
-                      divider: { enabled: false },
-                      image: { enabled: false },
-                  }
-                : {}),
-            ...unitsConfig,
-            'custom#e-sign': eSignComponentRecipients,
-        },
-        editor: {
-            autoSelectOnDrop: true,
-        },
-        customJS: customScripts,
-        customCSS: customStyles,
-        id,
-        fonts: {
-            showDefaultFonts: false,
-            customFonts: unlayerSupportedFonts,
-        },
-        tabs: {
-            content: {},
-            body: {},
-            blocks: { enabled: false },
-        },
-    });
-
-    document.getElementById = currentFind;
+            customJS: customScripts,
+            customCSS: customStyles,
+            id,
+            fonts: {
+                showDefaultFonts: false,
+                customFonts: unlayerSupportedFonts,
+            },
+            tabs: {
+                content: {},
+                body: {},
+                blocks: { enabled: false },
+            },
+        });
+    } catch (error: unknown) {
+        logUnlayerError('unlayer.createEditor failed', error);
+        throw error;
+    } finally {
+        document.getElementById = currentFind;
+    }
 
     if (displayConditions) {
         result.registerCallback(