@servicetitan/dte-unlayer 0.152.0 → 0.154.0

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

@@ -20,6 +20,22 @@ const renewalDateTag = {
     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 => {
@@ -46,21 +62,7 @@ describe('toUnlayerMergeTags', () => {
         const subject = () => toUnlayerMergeTags([contractTermTag, renewalDateTag]);
 
         test('nests tags under a submenu named by the host group', () => {
-            expect(subject()).toEqual({
-                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 }}',
-                        },
-                    },
-                },
-            });
+            expect(subject()).toEqual(groupedCustomFields);
         });
     });
 
@@ -73,10 +75,10 @@ describe('toUnlayerMergeTags', () => {
                     name: 'Customer Name',
                     value: '{{Customer.Name | safe | nl2br }}',
                 },
-                custom_fields: {
+                'custom_fields': {
                     name: 'Custom Fields',
                     mergeTags: {
-                        'custom-field-12345': {
+                        custom_field_12345: {
                             name: 'Contract Term',
                             value: '{{ __custom_fields["Contract Term"] | safe | nl2br }}',
                         },
@@ -103,7 +105,7 @@ describe('toUnlayerMergeTags', () => {
                 custom_fields: {
                     name: 'Custom Fields',
                     mergeTags: {
-                        'custom-field-12345': {
+                        custom_field_12345: {
                             name: 'Contract Term',
                             value: '{{ __custom_fields["Contract Term"] | safe | nl2br }}',
                         },
@@ -122,6 +124,101 @@ describe('toUnlayerMergeTags', () => {
         });
     });
 
+    describe('when group is a path', () => {
+        const intakeScoreTag = {
+            id: 'form-7-abc123',
+            name: 'Score',
+            propertyPath: '{{ __submission_fields["7"]["abc123"] | safe | nl2br }}',
+            group: ['Forms', 'Customer Intake'],
+        };
+        const intakeNotesTag = {
+            id: 'form-7-def456',
+            name: 'Notes',
+            propertyPath: '{{ __submission_fields["7"]["def456"] | safe | nl2br }}',
+            group: ['Forms', 'Customer Intake'],
+        };
+        const inspectionDateTag = {
+            id: 'form-9-fed987',
+            name: 'Inspection Date',
+            propertyPath: '{{ __submission_fields["9"]["fed987"] | safe | nl2br }}',
+            group: ['Forms', 'Inspection'],
+        };
+
+        const subject = () =>
+            toUnlayerMergeTags([
+                contractTermTag,
+                renewalDateTag,
+                intakeScoreTag,
+                intakeNotesTag,
+                inspectionDateTag,
+            ]);
+
+        test('nests one submenu per path segment', () => {
+            expect(subject()).toEqual({
+                ...groupedCustomFields,
+                forms: {
+                    name: 'Forms',
+                    mergeTags: {
+                        customer_intake: {
+                            name: 'Customer Intake',
+                            mergeTags: {
+                                form_7_abc123: {
+                                    name: 'Score',
+                                    value: '{{ __submission_fields["7"]["abc123"] | safe | nl2br }}',
+                                },
+                                form_7_def456: {
+                                    name: 'Notes',
+                                    value: '{{ __submission_fields["7"]["def456"] | safe | nl2br }}',
+                                },
+                            },
+                        },
+                        inspection: {
+                            name: 'Inspection',
+                            mergeTags: {
+                                form_9_fed987: {
+                                    name: 'Inspection Date',
+                                    value: '{{ __submission_fields["9"]["fed987"] | safe | nl2br }}',
+                                },
+                            },
+                        },
+                    },
+                },
+            });
+        });
+
+        test('drops blank segments and keeps the remaining path', () => {
+            expect(toUnlayerMergeTags([{ ...intakeScoreTag, group: [' ', 'Forms', ''] }])).toEqual({
+                forms: {
+                    name: 'Forms',
+                    mergeTags: {
+                        form_7_abc123: {
+                            name: 'Score',
+                            value: '{{ __submission_fields["7"]["abc123"] | safe | nl2br }}',
+                        },
+                    },
+                },
+            });
+        });
+
+        test('treats an all-blank path as ungrouped', () => {
+            expect(toUnlayerMergeTags([{ ...intakeScoreTag, group: [] }])).toEqual({
+                form_7_abc123: {
+                    name: 'Score',
+                    value: '{{ __submission_fields["7"]["abc123"] | safe | nl2br }}',
+                },
+            });
+        });
+
+        test('flattens the path when groups are disabled', () => {
+            expect(toUnlayerMergeTags([intakeScoreTag], { groups: false })).toEqual({
+                form_7_abc123: {
+                    name: 'Score',
+                    value: '{{ __submission_fields["7"]["abc123"] | safe | nl2br }}',
+                },
+            });
+        });
+    });
+
     describe('when group is blank', () => {
         const subject = () =>
             toUnlayerMergeTags([
@@ -140,4 +237,22 @@ describe('toUnlayerMergeTags', () => {
             });
         });
     });
+
+    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 }}',
+                },
+            });
+        });
+    });
 });

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

@@ -0,0 +1,186 @@
+import { UnlayerStore } from '../store';
+import type { CreateUnlayerEditorProps } from '../unlayer-interface';
+
+const editorMock = {
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    registerCallback: jest.fn(),
+    unregisterCallback: jest.fn(),
+    setMergeTags: jest.fn(),
+    loadDesign: jest.fn(),
+    setBodyValues: jest.fn(),
+};
+
+jest.mock('../loadScript', () => ({ loadScript: jest.fn().mockResolvedValue(undefined) }));
+jest.mock('../unlayer', () => ({
+    ...jest.requireActual('../unlayer'),
+    createUnlayerEditor: jest.fn(() => editorMock),
+}));
+
+const customerNameTag = {
+    id: '10',
+    name: 'Customer Name',
+    propertyPath: '{{Customer.Name | safe | nl2br }}',
+};
+
+const scoreTag = {
+    id: 'form-7-abc',
+    name: 'Score',
+    propertyPath: '{{ __submission_fields["7"]["abc"] | safe | nl2br }}',
+    group: ['Forms', 'Customer Intake'],
+};
+
+const flatCustomer = {
+    '10': { name: 'Customer Name', value: '{{Customer.Name | safe | nl2br }}' },
+};
+
+const groupedScore = {
+    forms: {
+        name: 'Forms',
+        mergeTags: {
+            customer_intake: {
+                name: 'Customer Intake',
+                mergeTags: {
+                    form_7_abc: {
+                        name: 'Score',
+                        value: '{{ __submission_fields["7"]["abc"] | safe | nl2br }}',
+                    },
+                },
+            },
+        },
+    },
+};
+
+const fireEditorEvent = (event: string) => {
+    editorMock.addEventListener.mock.calls
+        .filter(([name]) => name === event)
+        .forEach(([, handler]) => handler());
+};
+
+describe('UnlayerStore merge tags', () => {
+    let store: UnlayerStore;
+    let consoleError: jest.SpyInstance;
+
+    const createStore = (props: Partial<CreateUnlayerEditorProps> = {}) => {
+        store = new UnlayerStore({ tools: [], ...props });
+        return store;
+    };
+
+    const initStore = async () => {
+        (window as any).unlayer = {};
+        const container = document.createElement('div');
+        container.appendChild(document.createElement('iframe'));
+        await store.init(container);
+    };
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    });
+
+    afterEach(() => {
+        store.destroy();
+        consoleError.mockRestore();
+    });
+
+    describe('when the editor initializes with merge tags', () => {
+        beforeEach(async () => {
+            createStore({ mergeTags: [customerNameTag, scoreTag] });
+            await initStore();
+        });
+
+        test('does not touch the editor before it is ready', () => {
+            expect(editorMock.setMergeTags).not.toHaveBeenCalled();
+        });
+
+        test('applies the grouped shape once on editor:ready', () => {
+            fireEditorEvent('editor:ready');
+            fireEditorEvent('design:loaded');
+
+            expect(editorMock.setMergeTags).toHaveBeenCalledTimes(1);
+            expect(editorMock.setMergeTags).toHaveBeenCalledWith({
+                ...flatCustomer,
+                ...groupedScore,
+            });
+        });
+
+        test('applies on design:loaded when editor:ready never fires', () => {
+            fireEditorEvent('design:loaded');
+
+            expect(editorMock.setMergeTags).toHaveBeenCalledTimes(1);
+            expect(editorMock.setMergeTags).toHaveBeenCalledWith({
+                ...flatCustomer,
+                ...groupedScore,
+            });
+        });
+
+        test('retries on design:loaded when the first apply throws', () => {
+            editorMock.setMergeTags.mockImplementationOnce(() => {
+                throw new Error('not ready');
+            });
+
+            fireEditorEvent('editor:ready');
+            fireEditorEvent('design:loaded');
+            fireEditorEvent('design:loaded');
+
+            expect(editorMock.setMergeTags).toHaveBeenCalledTimes(2);
+            expect(consoleError).toHaveBeenCalledWith(
+                '[dte-unlayer]',
+                'Failed to apply merge tags',
+                expect.any(Error),
+            );
+        });
+    });
+
+    describe('with setMergeTags', () => {
+        describe('when called before the editor is ready', () => {
+            beforeEach(async () => {
+                createStore({ mergeTags: [customerNameTag] });
+                store.unlayerRef.setMergeTags([customerNameTag, scoreTag]);
+                await initStore();
+            });
+
+            test('replaces the initial tags and applies once on ready', () => {
+                fireEditorEvent('editor:ready');
+
+                expect(editorMock.setMergeTags).toHaveBeenCalledTimes(1);
+                expect(editorMock.setMergeTags).toHaveBeenCalledWith({
+                    ...flatCustomer,
+                    ...groupedScore,
+                });
+            });
+        });
+
+        describe('when called after the editor is ready', () => {
+            beforeEach(async () => {
+                createStore({ mergeTags: [customerNameTag] });
+                await initStore();
+                fireEditorEvent('editor:ready');
+                editorMock.setMergeTags.mockClear();
+            });
+
+            test('applies immediately', () => {
+                store.unlayerRef.setMergeTags([customerNameTag, scoreTag]);
+
+                expect(editorMock.setMergeTags).toHaveBeenCalledTimes(1);
+                expect(editorMock.setMergeTags).toHaveBeenCalledWith({
+                    ...flatCustomer,
+                    ...groupedScore,
+                });
+            });
+
+            test('does not re-apply on later design:loaded events', () => {
+                store.unlayerRef.setMergeTags([customerNameTag, scoreTag]);
+                fireEditorEvent('design:loaded');
+
+                expect(editorMock.setMergeTags).toHaveBeenCalledTimes(1);
+            });
+
+            test('ignores an empty set', () => {
+                store.unlayerRef.setMergeTags([]);
+
+                expect(editorMock.setMergeTags).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,7 +3,13 @@ export * from './tools';
 export * from './api-core';
 export * from './api-custom-tools';
 export * from './unlayer-interface';
-export * from './merge-tags';
+export { isUnlayerMergeTagGroup, toUnlayerMergeTags } from './merge-tags';
+export type {
+    ToUnlayerMergeTagsOptions,
+    UnlayerMergeTagGroup,
+    UnlayerMergeTagLeaf,
+    UnlayerMergeTagsConfig,
+} 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

@@ -7,58 +7,92 @@ export interface UnlayerMergeTagLeaf {
 
 export interface UnlayerMergeTagGroup {
     name: string;
-    mergeTags: Record<string, UnlayerMergeTagLeaf>;
+    /** Nested submenu: leaves and/or further groups (Unlayer supports arbitrary depth). */
+    mergeTags: UnlayerMergeTagsConfig;
 }
 
 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 function isUnlayerMergeTagGroup(
     entry: UnlayerMergeTagLeaf | UnlayerMergeTagGroup,
 ): entry is UnlayerMergeTagGroup {
     return 'mergeTags' in entry;
 }
 
-const toMergeTagGroupKey = (groupName: string) => {
-    const key = groupName
+const toMergeTagKey = (value: string) => {
+    const key = value
         .toLowerCase()
         .split(/[^a-z0-9]+/)
         .filter(Boolean)
         .join('_');
 
-    return key || groupName;
+    return key || value;
+};
+
+/**
+ * Normalizes the host `group` into the submenu path the tag belongs to:
+ * `'Custom Fields'` → `['Custom Fields']`, `['Forms', 'Intake']` → `['Forms', 'Intake']`.
+ * Blank segments are dropped; an empty result means the tag stays at the top level.
+ */
+const toGroupPath = (group: UnlayerEditorMergeTagInfo['group']): string[] => {
+    const segments = Array.isArray(group) ? group : group === undefined ? [] : [group];
+
+    return segments.map(segment => segment.trim()).filter(Boolean);
+};
+
+/** Returns the `mergeTags` record of the (possibly nested) group at `path`, creating groups on the way. */
+const ensureGroup = (root: UnlayerMergeTagsConfig, path: string[]) => {
+    let current = root;
+
+    for (const groupName of path) {
+        const groupKey = toMergeTagKey(groupName);
+        const existing = current[groupKey];
+
+        if (existing && isUnlayerMergeTagGroup(existing)) {
+            current = existing.mergeTags;
+            continue;
+        }
+
+        const created: UnlayerMergeTagGroup = { name: groupName, mergeTags: {} };
+        current[groupKey] = created;
+        current = created.mergeTags;
+    }
+
+    return current;
 };
 
-export const toUnlayerMergeTags = (tags: UnlayerEditorMergeTagInfo[] | undefined) => {
+/**
+ * Builds Unlayer's `mergeTags` config. With `groups` enabled (default) tags nest under the
+ * submenu path in `group`; `UnlayerStore` applies that shape once the editor is ready, since
+ * nested groups at `createEditor` time prevent DTE custom tools from loading.
+ */
+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 groupName = tag.group?.trim();
-
-        if (!groupName) {
-            out[tag.id] = mergeTag;
-            return out;
-        }
+        const tagKey = toMergeTagKey(tag.id);
+        const groupPath = groupsEnabled ? toGroupPath(tag.group) : [];
 
-        const groupKey = toMergeTagGroupKey(groupName);
-        const existing = out[groupKey];
-
-        if (existing && isUnlayerMergeTagGroup(existing)) {
-            existing.mergeTags[tag.id] = mergeTag;
-            return out;
-        }
-
-        out[groupKey] = {
-            name: groupName,
-            mergeTags: {
-                [tag.id]: mergeTag,
-            },
-        };
+        ensureGroup(out, groupPath)[tagKey] = mergeTag;
 
         return out;
     }, {});

package/src/shared/instance-id.ts

@@ -0,0 +1,23 @@
+/**
+ * Custom tools whose `values.id` is a per-instance GUID that must stay unique
+ * within a design. When such a tool is duplicated (content or row duplicate),
+ * Unlayer copies the values as-is, so the host regenerates the id of the copy.
+ */
+export const INSTANCE_ID_TOOL_SLUGS = ['embedded-image'];
+
+/**
+ * Generates an RFC 4122 v4 GUID (`3fa85f64-5717-4562-b3fc-2c963f66afa6`) with the
+ * platform `crypto.randomUUID()`. It is only exposed in secure contexts (https /
+ * localhost); when missing the error is logged and no id is produced.
+ */
+export const generateInstanceId = (): string | undefined => {
+    if (typeof globalThis.crypto?.randomUUID !== 'function') {
+        // eslint-disable-next-line no-console
+        console.error(
+            'crypto.randomUUID is not available (insecure context?), cannot generate an instance id',
+        );
+        return undefined;
+    }
+
+    return globalThis.crypto.randomUUID();
+};