@servicetitan/dte-unlayer 0.151.0 → 0.153.0

package/src/__tests__/log.test.ts

@@ -0,0 +1,44 @@
+import { getErrorMessage, logUnlayerError } from '../log';
+
+describe('getErrorMessage', () => {
+    describe('when error is an Error', () => {
+        const subject = () => getErrorMessage(new Error('createEditor failed'));
+
+        test('returns the error message', () => {
+            expect(subject()).toBe('createEditor failed');
+        });
+    });
+
+    describe('when error is a string', () => {
+        const subject = () => getErrorMessage('script load failed');
+
+        test('returns the string', () => {
+            expect(subject()).toBe('script load failed');
+        });
+    });
+
+    describe('when error is unknown', () => {
+        test.each([undefined, null, 0, {}])('returns a fallback for %p', error => {
+            expect(getErrorMessage(error)).toBe('Unknown Unlayer error');
+        });
+    });
+});
+
+describe('logUnlayerError', () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    test('writes a prefixed console error with the cause', () => {
+        const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+        const error = new Error('createEditor failed');
+
+        logUnlayerError('Failed to initialize Unlayer editor', error);
+
+        expect(consoleError).toHaveBeenCalledWith(
+            '[dte-unlayer]',
+            'Failed to initialize Unlayer editor',
+            error,
+        );
+    });
+});

package/src/__tests__/merge-tags.test.ts

@@ -0,0 +1,236 @@
+import { scheduleUnlayerMergeTags, toUnlayerMergeTags } from '../merge-tags';
+
+const customerNameTag = {
+    id: '10',
+    name: 'Customer Name',
+    propertyPath: '{{Customer.Name | safe | nl2br }}',
+};
+
+const contractTermTag = {
+    id: 'custom-field-12345',
+    name: 'Contract Term',
+    propertyPath: '{{ __custom_fields["Contract Term"] | safe | nl2br }}',
+    group: 'Custom Fields',
+};
+
+const renewalDateTag = {
+    id: 'custom-field-12346',
+    name: 'Renewal Date',
+    propertyPath: '{{ __custom_fields["Renewal Date"] | safe | nl2br }}',
+    group: 'Custom Fields',
+};
+
+const groupedCustomFields = {
+    custom_fields: {
+        name: 'Custom Fields',
+        mergeTags: {
+            custom_field_12345: {
+                name: 'Contract Term',
+                value: '{{ __custom_fields["Contract Term"] | safe | nl2br }}',
+            },
+            custom_field_12346: {
+                name: 'Renewal Date',
+                value: '{{ __custom_fields["Renewal Date"] | safe | nl2br }}',
+            },
+        },
+    },
+};
+
+describe('toUnlayerMergeTags', () => {
+    describe('when tags are missing', () => {
+        test.each([undefined, []])('returns undefined for %p', tags => {
+            const subject = () => toUnlayerMergeTags(tags);
+
+            expect(subject()).toBeUndefined();
+        });
+    });
+
+    describe('when tags have no group', () => {
+        const subject = () => toUnlayerMergeTags([customerNameTag]);
+
+        test('returns flat merge tags', () => {
+            expect(subject()).toEqual({
+                '10': {
+                    name: 'Customer Name',
+                    value: '{{Customer.Name | safe | nl2br }}',
+                },
+            });
+        });
+    });
+
+    describe('when tags have a group', () => {
+        const subject = () => toUnlayerMergeTags([contractTermTag, renewalDateTag]);
+
+        test('nests tags under a submenu named by the host group', () => {
+            expect(subject()).toEqual(groupedCustomFields);
+        });
+    });
+
+    describe('when tags mix grouped and ungrouped', () => {
+        const subject = () => toUnlayerMergeTags([customerNameTag, contractTermTag]);
+
+        test('keeps ungrouped tags flat and grouped tags nested', () => {
+            expect(subject()).toEqual({
+                '10': {
+                    name: 'Customer Name',
+                    value: '{{Customer.Name | safe | nl2br }}',
+                },
+                custom_fields: {
+                    name: 'Custom Fields',
+                    mergeTags: {
+                        custom_field_12345: {
+                            name: 'Contract Term',
+                            value: '{{ __custom_fields["Contract Term"] | safe | nl2br }}',
+                        },
+                    },
+                },
+            });
+        });
+    });
+
+    describe('when tags use more than one group', () => {
+        const subject = () =>
+            toUnlayerMergeTags([
+                contractTermTag,
+                {
+                    id: 'street',
+                    name: 'Street 1',
+                    propertyPath: '{{shipping_address.address_1}}',
+                    group: 'Shipping Address',
+                },
+            ]);
+
+        test('creates a submenu per host group label', () => {
+            expect(subject()).toEqual({
+                custom_fields: {
+                    name: 'Custom Fields',
+                    mergeTags: {
+                        custom_field_12345: {
+                            name: 'Contract Term',
+                            value: '{{ __custom_fields["Contract Term"] | safe | nl2br }}',
+                        },
+                    },
+                },
+                shipping_address: {
+                    name: 'Shipping Address',
+                    mergeTags: {
+                        street: {
+                            name: 'Street 1',
+                            value: '{{shipping_address.address_1}}',
+                        },
+                    },
+                },
+            });
+        });
+    });
+
+    describe('when group is blank', () => {
+        const subject = () =>
+            toUnlayerMergeTags([
+                {
+                    ...customerNameTag,
+                    group: '   ',
+                },
+            ]);
+
+        test('treats the tag as ungrouped', () => {
+            expect(subject()).toEqual({
+                '10': {
+                    name: 'Customer Name',
+                    value: '{{Customer.Name | safe | nl2br }}',
+                },
+            });
+        });
+    });
+
+    describe('when groups are disabled', () => {
+        const subject = () =>
+            toUnlayerMergeTags([customerNameTag, contractTermTag], { groups: false });
+
+        test('keeps every tag flat like Unlayer 0.151', () => {
+            expect(subject()).toEqual({
+                '10': {
+                    name: 'Customer Name',
+                    value: '{{Customer.Name | safe | nl2br }}',
+                },
+                custom_field_12345: {
+                    name: 'Contract Term',
+                    value: '{{ __custom_fields["Contract Term"] | safe | nl2br }}',
+                },
+            });
+        });
+    });
+});
+
+describe('scheduleUnlayerMergeTags', () => {
+    describe('when grouped tags exist', () => {
+        const setMergeTags = jest.fn();
+        const addEventListener = jest.fn();
+
+        beforeEach(() => {
+            setMergeTags.mockReset();
+            addEventListener.mockReset();
+            scheduleUnlayerMergeTags(
+                { addEventListener, setMergeTags },
+                [customerNameTag, contractTermTag, renewalDateTag],
+            );
+        });
+
+        test('does not apply grouped merge tags until the editor is ready', () => {
+            expect(setMergeTags).not.toHaveBeenCalled();
+            expect(addEventListener).toHaveBeenCalledWith('editor:ready', expect.any(Function));
+            expect(addEventListener).toHaveBeenCalledWith('design:loaded', expect.any(Function));
+        });
+
+        test('applies grouped merge tags when the editor is ready', () => {
+            addEventListener.mock.calls[0][1]();
+
+            expect(setMergeTags).toHaveBeenCalledWith({
+                '10': {
+                    name: 'Customer Name',
+                    value: '{{Customer.Name | safe | nl2br }}',
+                },
+                ...groupedCustomFields,
+            });
+        });
+
+        test('applies grouped merge tags only once', () => {
+            addEventListener.mock.calls[0][1]();
+            addEventListener.mock.calls[1][1]();
+
+            expect(setMergeTags).toHaveBeenCalledTimes(1);
+        });
+
+        test('retries on design:loaded when setMergeTags throws', () => {
+            const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+            setMergeTags.mockImplementationOnce(() => {
+                throw new Error('setMergeTags failed');
+            });
+
+            addEventListener.mock.calls[0][1]();
+            addEventListener.mock.calls[1][1]();
+
+            expect(setMergeTags).toHaveBeenCalledTimes(2);
+            expect(consoleError).toHaveBeenCalledWith(
+                '[dte-unlayer]',
+                'Failed to apply grouped merge tags',
+                expect.any(Error),
+            );
+            consoleError.mockRestore();
+        });
+    });
+
+    describe('when tags are missing', () => {
+        const setMergeTags = jest.fn();
+        const addEventListener = jest.fn();
+
+        beforeEach(() => {
+            scheduleUnlayerMergeTags({ addEventListener, setMergeTags }, undefined);
+        });
+
+        test('does not touch the editor', () => {
+            expect(setMergeTags).not.toHaveBeenCalled();
+            expect(addEventListener).not.toHaveBeenCalled();
+        });
+    });
+});

package/src/editor.tsx

@@ -8,6 +8,7 @@ import {
     useState,
 } from 'react';
 import { DisplayConditionModal } from './display-conditions/DisplayConditionModal';
+import { getErrorMessage } from './log';
 import { UnlayerEditorTwin } from './shared/const';
 import { UnlayerStore, UnlayerDesignChangeInfo } from './store';
 import { UnlayerRef, CreateUnlayerEditorProps } from './unlayer-interface';
@@ -36,6 +37,7 @@ export const useUnlayerRef = () => useRef<UnlayerRef | null>(null);
 
 export const UnlayerEditor = forwardRef<UnlayerRef, UnlayerEditorProps>((props, ref) => {
     const [isReady, setIsReady] = useState(false);
+    const [loadError, setLoadError] = useState<string>();
     const containerRef = useRef<HTMLDivElement | null>(null);
     const store = useMemo(
         () => new UnlayerStore(props.opts),
@@ -43,15 +45,30 @@ export const UnlayerEditor = forwardRef<UnlayerRef, UnlayerEditorProps>((props,
         [],
     );
 
+    useEffect(() => {
+        store.setOnError(props.onError);
+
+        return () => store.setOnError();
+    }, [props.onError, store]);
+
     useEffect(() => {
         if (containerRef.current) {
             store
                 .init(containerRef.current)
-                .then(() => setIsReady(true))
-                .catch(() => setIsReady(false));
+                .then(() => {
+                    setLoadError(undefined);
+                    setIsReady(true);
+                })
+                .catch((error: unknown) => {
+                    const description = getErrorMessage(error);
+                    setIsReady(false);
+                    setLoadError(description);
+                    props.onError?.('Editor failed to load', description);
+                });
         }
 
         return () => store.destroy();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [store]);
     useImperativeHandle(ref, () => store.unlayerRef, [store]);
 
@@ -91,12 +108,6 @@ export const UnlayerEditor = forwardRef<UnlayerRef, UnlayerEditorProps>((props,
         return () => store.setOnImage();
     }, [props.onImage, store]);
 
-    useEffect(() => {
-        store.setOnError(props.onError);
-
-        return () => store.setOnError();
-    }, [props.onError, store]);
-
     useEffect(() => {
         store.setOnMessage(props.onMessage);
 
@@ -125,7 +136,7 @@ export const UnlayerEditor = forwardRef<UnlayerRef, UnlayerEditorProps>((props,
 
     return (
         <div style={{ minHeight, display: 'flex' }}>
-            {!isReady && <p className="c-red-500">error loading editor</p>}
+            {loadError && <p className="c-red-500">error loading editor: {loadError}</p>}
             <div id={props.id ?? 'editor'} style={style} ref={containerRef} />
             {props.opts.displayConditions && (
                 <DisplayConditionModal

package/src/index.ts

@@ -3,6 +3,14 @@ export * from './tools';
 export * from './api-core';
 export * from './api-custom-tools';
 export * from './unlayer-interface';
+export { isUnlayerMergeTagGroup, scheduleUnlayerMergeTags, toUnlayerMergeTags } from './merge-tags';
+export type {
+    ToUnlayerMergeTagsOptions,
+    UnlayerMergeTagGroup,
+    UnlayerMergeTagLeaf,
+    UnlayerMergeTagsConfig,
+    UnlayerMergeTagsEditor,
+} from './merge-tags';
 export * from './loadScript';
 export * from './shared/const';
 export * from './shared/forms';

package/src/loadScript.ts

@@ -1,3 +1,5 @@
+import { logUnlayerError } from './log';
+
 const isScriptInjected = (scriptUrl: string) => {
     const scripts = document.querySelectorAll('script');
     let injected = false;
@@ -12,9 +14,10 @@ const isScriptInjected = (scriptUrl: string) => {
 };
 
 export const loadScript = (scriptUrl: string): Promise<void> => {
-    return new Promise<void>(resolve => {
+    return new Promise<void>((resolve, reject) => {
         if (isScriptInjected(scriptUrl)) {
             resolve();
+            return;
         }
 
         const embedScript = document.createElement('script');
@@ -22,6 +25,11 @@ export const loadScript = (scriptUrl: string): Promise<void> => {
         embedScript.onload = () => {
             resolve();
         };
+        embedScript.onerror = () => {
+            const error = new Error(`Failed to load Unlayer script: ${scriptUrl}`);
+            logUnlayerError('Unlayer embed script failed to load', error);
+            reject(error);
+        };
         document.head.appendChild(embedScript);
     });
 };

package/src/log.ts

@@ -0,0 +1,24 @@
+const LOG_PREFIX = '[dte-unlayer]';
+
+export const getErrorMessage = (error: unknown) => {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+
+    if (typeof error === 'string' && error) {
+        return error;
+    }
+
+    return 'Unknown Unlayer error';
+};
+
+export const logUnlayerError = (message: string, error?: unknown) => {
+    if (error === undefined) {
+        // eslint-disable-next-line no-console
+        console.error(LOG_PREFIX, message);
+        return;
+    }
+
+    // eslint-disable-next-line no-console
+    console.error(LOG_PREFIX, message, error);
+};

package/src/merge-tags.ts

@@ -0,0 +1,118 @@
+import { logUnlayerError } from './log';
+import { UnlayerEditorMergeTagInfo } from './unlayer-interface';
+
+export interface UnlayerMergeTagLeaf {
+    name: string;
+    value: string;
+}
+
+export interface UnlayerMergeTagGroup {
+    name: string;
+    mergeTags: Record<string, UnlayerMergeTagLeaf>;
+}
+
+export type UnlayerMergeTagsConfig = Record<string, UnlayerMergeTagLeaf | UnlayerMergeTagGroup>;
+
+export interface ToUnlayerMergeTagsOptions {
+    /**
+     * When false, ignore `group` and emit the flat 0.151 shape. Unlayer custom
+     * tools fail to register if nested groups are present during createEditor.
+     */
+    groups?: boolean;
+}
+
+export interface UnlayerMergeTagsEditor {
+    addEventListener(event: string, cb: (arg: any) => void): void;
+    setMergeTags(tags: UnlayerMergeTagsConfig): void;
+}
+
+export function isUnlayerMergeTagGroup(
+    entry: UnlayerMergeTagLeaf | UnlayerMergeTagGroup,
+): entry is UnlayerMergeTagGroup {
+    return 'mergeTags' in entry;
+}
+
+const toMergeTagKey = (value: string) => {
+    const key = value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean)
+        .join('_');
+
+    return key || value;
+};
+
+export const toUnlayerMergeTags = (
+    tags: UnlayerEditorMergeTagInfo[] | undefined,
+    options?: ToUnlayerMergeTagsOptions,
+) => {
+    if (!tags?.length) {
+        return undefined;
+    }
+
+    const groupsEnabled = options?.groups !== false;
+
+    return tags.reduce<UnlayerMergeTagsConfig>((out, tag) => {
+        const mergeTag: UnlayerMergeTagLeaf = {
+            name: tag.name,
+            value: tag.propertyPath,
+        };
+        const tagKey = toMergeTagKey(tag.id);
+        const groupName = groupsEnabled ? tag.group?.trim() : undefined;
+
+        if (!groupName) {
+            out[tagKey] = mergeTag;
+            return out;
+        }
+
+        const groupKey = toMergeTagKey(groupName);
+        const existing = out[groupKey];
+
+        if (existing && isUnlayerMergeTagGroup(existing)) {
+            existing.mergeTags[tagKey] = mergeTag;
+            return out;
+        }
+
+        out[groupKey] = {
+            name: groupName,
+            mergeTags: {
+                [tagKey]: mergeTag,
+            },
+        };
+
+        return out;
+    }, {});
+};
+
+/**
+ * Nested Unlayer groups passed to createEditor prevent DTE custom tools from
+ * loading in the host app. Apply the 0.151 flat shape at init, then upgrade to
+ * grouped submenus once the editor (and customJS tools) are ready.
+ */
+export const scheduleUnlayerMergeTags = (
+    editor: UnlayerMergeTagsEditor,
+    tags: UnlayerEditorMergeTagInfo[] | undefined,
+) => {
+    const grouped = toUnlayerMergeTags(tags);
+
+    if (!grouped) {
+        return;
+    }
+
+    let isApplied = false;
+    const apply = () => {
+        if (isApplied) {
+            return;
+        }
+
+        try {
+            editor.setMergeTags(grouped);
+            isApplied = true;
+        } catch (error: unknown) {
+            logUnlayerError('Failed to apply grouped merge tags', error);
+        }
+    };
+
+    editor.addEventListener('editor:ready', apply);
+    editor.addEventListener('design:loaded', apply);
+};

package/src/store.ts

@@ -1,4 +1,5 @@
 import { loadScript } from './loadScript';
+import { logUnlayerError } from './log';
 import { defaultImageValidation } from './shared/configs';
 import type { UnlayerEditorTwin, UnlayerEventConfig, UnlayerEventRegister } from './shared/const';
 import { unlayerSupportedFonts } from './shared/fonts';
@@ -20,6 +21,7 @@ import {
 import { CreateUnlayerEditorProps, UnlayerDesignFormat, 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,6 +186,9 @@ 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> = {};
 
@@ -241,19 +246,37 @@ 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);
+            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) {
@@ -392,8 +415,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 +614,7 @@ export class UnlayerStore {
         });
 
         if (!res.isValid) {
+            logUnlayerError(`Image validation failed: ${res.title}`, res.description);
             this.onErrorCB?.(res.title, res.description);
             return;
         }
@@ -597,7 +624,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 +634,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/unlayer-interface.tsx

@@ -51,6 +51,7 @@ export interface UnlayerEditorMergeTagInfo {
     id: string;
     name: string;
     propertyPath: string;
+    group?: string;
 }
 
 export interface UnlayerEditorCustomTool {