@servicetitan/dte-unlayer 0.153.0 → 0.155.0

package/src/editor.tsx

@@ -8,6 +8,7 @@ import {
     useState,
 } from 'react';
 import { DisplayConditionModal } from './display-conditions/DisplayConditionModal';
+import { ESignDateSignedOffsetModal } from './e-sign-offset/ESignDateSignedOffsetModal';
 import { getErrorMessage } from './log';
 import { UnlayerEditorTwin } from './shared/const';
 import { UnlayerStore, UnlayerDesignChangeInfo } from './store';
@@ -146,6 +147,14 @@ export const UnlayerEditor = forwardRef<UnlayerRef, UnlayerEditorProps>((props,
                     onConditionFormSelect={props.opts.onConditionFormSelect}
                 />
             )}
+            {!!props.opts.eSignRecipients?.length && (
+                <ESignDateSignedOffsetModal
+                    portalContainer={props.opts.displayConditionModalPortalContainer}
+                    schema={props.opts.schema}
+                    onConditionalsOpen={props.opts.onConditionalsOpen}
+                    onConditionFormSelect={props.opts.onConditionFormSelect}
+                />
+            )}
         </div>
     );
 });

package/src/index.ts

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

package/src/merge-tags.ts

@@ -1,4 +1,3 @@
-import { logUnlayerError } from './log';
 import { UnlayerEditorMergeTagInfo } from './unlayer-interface';
 
 export interface UnlayerMergeTagLeaf {
@@ -8,7 +7,8 @@ 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>;
@@ -21,11 +21,6 @@ export interface ToUnlayerMergeTagsOptions {
     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 {
@@ -42,6 +37,43 @@ const toMergeTagKey = (value: string) => {
     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;
+};
+
+/**
+ * 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,
@@ -58,61 +90,10 @@ export const toUnlayerMergeTags = (
             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;
-        }
+        const groupPath = groupsEnabled ? toGroupPath(tag.group) : [];
 
-        out[groupKey] = {
-            name: groupName,
-            mergeTags: {
-                [tagKey]: mergeTag,
-            },
-        };
+        ensureGroup(out, groupPath)[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/shared/const.ts

@@ -1,3 +1,4 @@
+import type { DisplayConditionState } from '../display-conditions/types';
 import { SchemaObject } from './schema';
 
 export const constGenericsEditor = {
@@ -12,6 +13,41 @@ export interface UnlayerEditorESignRecipientInfo {
     displayName: string;
 }
 
+export const E_SIGN_TOOL_SLUG = 'e-sign';
+export const E_SIGN_DATE_SIGNED_OFFSET_TYPE = 'dateSignedOffset';
+/** Must match the backend `EsignFieldSubTypes` registry key read from the e-sign tool values. */
+export const E_SIGN_DATE_SIGNED_OFFSET_VALUES_KEY = 'eSignDateSignedOffset';
+export const MAX_E_SIGN_OFFSET_DAYS = 365;
+/** Counts the trailing unconditional rule too. */
+export const MAX_E_SIGN_OFFSET_RULES = 5;
+
+export interface ESignDateSignedOffsetRule {
+    days: number;
+    /** Always `behavior: 'show'` with exactly one condition; the backend rejects anything else. */
+    condition: DisplayConditionState;
+}
+
+export interface ESignDateSignedOffsetFinalRule {
+    days: number;
+    condition?: never;
+}
+
+/**
+ * Ordered if / else-if / else chain: the first rule whose condition matches supplies the offset,
+ * and the last rule is always the unconditional fallback.
+ */
+export interface ESignDateSignedOffsetSettings {
+    rules:
+        | [ESignDateSignedOffsetFinalRule]
+        | [...ESignDateSignedOffsetRule[], ESignDateSignedOffsetFinalRule];
+}
+
+/** Payload of both `--esign-offset-open` (iframe to parent) and `--esign-offset-result` (back). */
+export interface UnlayerEventESignOffset {
+    requestId: string;
+    value: ESignDateSignedOffsetSettings;
+}
+
 export interface UnlayerEditorUnit {
     id: string;
     generic: string;
@@ -33,6 +69,7 @@ export interface UnlayerEventConfig {
     isSnapshotMode?: boolean;
     units?: UnlayerEditorUnit[];
     holidays?: string[];
+    conditionalRulesEnabled?: boolean;
 }
 
 export interface UnlayerEventRegister {

package/src/shared/e-sign-offset.ts

@@ -0,0 +1,173 @@
+import { defaultGroup } from '../display-conditions/constants';
+import {
+    CONDITION_OPERATORS,
+    type DataPointOption,
+    type DisplayConditionState,
+    type SingleCondition,
+    VALUE_LESS_OPERATORS,
+} from '../display-conditions/types';
+import {
+    type ESignDateSignedOffsetFinalRule,
+    type ESignDateSignedOffsetRule,
+    type ESignDateSignedOffsetSettings,
+    MAX_E_SIGN_OFFSET_DAYS,
+    MAX_E_SIGN_OFFSET_RULES,
+} from './const';
+
+const NUMERIC_VALUE_RE = /^-?(?:\d+\.?\d*|\.\d+)$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isConditionState(value: unknown): value is DisplayConditionState {
+    return isRecord(value) && Array.isArray(value.groups) && value.groups.length > 0;
+}
+
+function isConditionedRule(
+    rule: ESignDateSignedOffsetRule | ESignDateSignedOffsetFinalRule,
+): rule is ESignDateSignedOffsetRule {
+    return rule.condition !== undefined;
+}
+
+export const clampESignOffsetDays = (days: unknown) => {
+    if (typeof days !== 'number' || !Number.isFinite(days)) {
+        return 0;
+    }
+
+    return Math.max(Math.min(MAX_E_SIGN_OFFSET_DAYS, Math.trunc(days)), 0);
+};
+
+export const createESignOffsetSettings = (days = 0): ESignDateSignedOffsetSettings => {
+    return { rules: [{ days: clampESignOffsetDays(days) }] };
+};
+
+export const createESignOffsetRule = (): ESignDateSignedOffsetRule => {
+    return { condition: { behavior: 'show', groups: [defaultGroup()] }, days: 0 };
+};
+
+export const buildESignOffsetSettings = (
+    conditionedRules: ESignDateSignedOffsetRule[],
+    finalDays: number,
+): ESignDateSignedOffsetSettings => {
+    return {
+        rules: [
+            ...conditionedRules.map(rule => ({ ...rule, days: clampESignOffsetDays(rule.days) })),
+            { days: clampESignOffsetDays(finalDays) },
+        ],
+    };
+};
+
+export const splitESignOffsetSettings = (settings: ESignDateSignedOffsetSettings) => {
+    const rules: readonly (ESignDateSignedOffsetRule | ESignDateSignedOffsetFinalRule)[] =
+        settings.rules;
+
+    return {
+        conditionedRules: rules.filter(isConditionedRule),
+        finalDays: rules[rules.length - 1]?.days ?? 0,
+    };
+};
+
+export function isESignOffsetSettings(value: unknown): value is ESignDateSignedOffsetSettings {
+    if (!isRecord(value) || !Array.isArray(value.rules)) {
+        return false;
+    }
+
+    const rules: unknown[] = value.rules;
+
+    if (rules.length === 0 || rules.length > MAX_E_SIGN_OFFSET_RULES) {
+        return false;
+    }
+
+    return rules.every((rule, index) => {
+        if (!isRecord(rule) || clampESignOffsetDays(rule.days) !== rule.days) {
+            return false;
+        }
+
+        return index === rules.length - 1
+            ? rule.condition === undefined
+            : isConditionState(rule.condition);
+    });
+}
+
+/** Coerces whatever is stored on the tool (missing, legacy or hand-edited) into a valid chain. */
+export const normalizeESignOffsetSettings = (value: unknown): ESignDateSignedOffsetSettings => {
+    if (isESignOffsetSettings(value)) {
+        return value;
+    }
+
+    if (!isRecord(value) || !Array.isArray(value.rules)) {
+        return createESignOffsetSettings();
+    }
+
+    const rules: unknown[] = value.rules;
+    const lastRule = rules[rules.length - 1];
+    const conditionedRules = rules
+        .slice(0, -1)
+        .flatMap(rule =>
+            isRecord(rule) && isConditionState(rule.condition)
+                ? [{ condition: rule.condition, days: clampESignOffsetDays(rule.days) }]
+                : [],
+        )
+        .slice(0, MAX_E_SIGN_OFFSET_RULES - 1);
+
+    return buildESignOffsetSettings(
+        conditionedRules,
+        isRecord(lastRule) ? clampESignOffsetDays(lastRule.days) : 0,
+    );
+};
+
+export const canAddESignOffsetRule = (rules: ESignDateSignedOffsetRule[]) => {
+    return rules.length < MAX_E_SIGN_OFFSET_RULES - 1;
+};
+
+export const addESignOffsetRule = (rules: ESignDateSignedOffsetRule[]) => {
+    return canAddESignOffsetRule(rules) ? [...rules, createESignOffsetRule()] : rules;
+};
+
+export const updateESignOffsetRule = (
+    rules: ESignDateSignedOffsetRule[],
+    index: number,
+    nextRule: ESignDateSignedOffsetRule,
+) => {
+    return rules.map((rule, ruleIndex) => (ruleIndex === index ? nextRule : rule));
+};
+
+export const removeESignOffsetRule = (rules: ESignDateSignedOffsetRule[], index: number) => {
+    return rules.filter((_, ruleIndex) => ruleIndex !== index);
+};
+
+export const getESignOffsetRuleCondition = (rule: ESignDateSignedOffsetRule) => {
+    return rule.condition.groups[0]?.conditions[0];
+};
+
+export const isCompleteESignOffsetCondition = (
+    condition: SingleCondition | undefined,
+    fieldType: DataPointOption['fieldType'],
+) => {
+    if (!condition?.dataPointKey) {
+        return false;
+    }
+
+    if (VALUE_LESS_OPERATORS.includes(condition.operator)) {
+        return true;
+    }
+
+    const value = condition.value.trim();
+
+    return value !== '' && (fieldType !== 'number' || NUMERIC_VALUE_RE.test(value));
+};
+
+export const getESignOffsetConditionText = (condition: SingleCondition, dataPointTitle: string) => {
+    const operatorLabel = (
+        CONDITION_OPERATORS.find(operator => operator.value === condition.operator)?.label ??
+        condition.operator
+    )
+        .split(' (')[0]
+        .replace('==', '=')
+        .toLowerCase();
+
+    return VALUE_LESS_OPERATORS.includes(condition.operator)
+        ? `${dataPointTitle} ${operatorLabel}`
+        : `${dataPointTitle} ${operatorLabel} ${condition.value}`;
+};

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();
+};

package/src/store.ts

@@ -1,7 +1,15 @@
+import { emitESignOffsetRequest } from './e-sign-offset/eSignOffsetController';
 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 type {
+    UnlayerEditorTwin,
+    UnlayerEventConfig,
+    UnlayerEventESignOffset,
+    UnlayerEventRegister,
+} from './shared/const';
+import { normalizeESignOffsetSettings } from './shared/e-sign-offset';
 import { unlayerSupportedFonts } from './shared/fonts';
 import {
     FormFieldInfo,
@@ -11,14 +19,23 @@ import {
 } from './shared/forms';
 import { schemaBuildMap, schemaIsDate } from './shared/schema';
 import { unlayerToolsParseTwinKey } from './shared/tools';
-import { unlayerToolsIterate } from './tools';
+import {
+    unlayerToolsDedupeInstanceIds,
+    unlayerToolsIterate,
+    unlayerToolsNormalizeESignOffsets,
+} 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;
@@ -191,6 +208,9 @@ export class UnlayerStore {
     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;
@@ -211,18 +231,28 @@ export class UnlayerStore {
                 .map(field => field.fullKey),
         );
 
-        this.props.eSignFieldTypes = ['Signature', 'Initials', 'Date Signed', 'Full Name'];
+        this.props.eSignFieldTypes = [
+            'Signature',
+            'Initials',
+            'Date Signed',
+            'Date Signed Offset',
+            'Full Name',
+        ];
 
         this.unlayerRef = {
             loadDesign: design => {
                 this.editor?.loadDesign(design);
             },
             saveDesign: cb => {
-                this.editor?.saveDesign(cb);
+                this.editor?.saveDesign(design => {
+                    unlayerToolsNormalizeESignOffsets(design);
+                    cb(design);
+                });
             },
             exportHtml: cb => {
                 this.editor?.exportHtml(data => {
                     const result = ensureChunksFonts(data);
+                    unlayerToolsNormalizeESignOffsets(result?.design);
                     result.demoData = this.buildCalculatedFieldDemoData(result.design);
                     cb(result);
                 });
@@ -236,6 +266,9 @@ export class UnlayerStore {
             sendCalcFieldLabels: labels => {
                 this.sendCalcFieldLabels(labels);
             },
+            setMergeTags: tags => {
+                this.setMergeTags(tags);
+            },
         };
     }
 
@@ -256,6 +289,9 @@ export class UnlayerStore {
             }
 
             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);
@@ -280,6 +316,7 @@ export class UnlayerStore {
         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);
@@ -355,7 +392,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({
@@ -391,6 +467,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);
                 }
@@ -427,6 +508,8 @@ export class UnlayerStore {
                 genericConfigMode: this.props.genericConfigMode,
                 isSnapshotMode: this.props.isSnapshotMode,
                 holidays: this.props.holidays,
+                conditionalRulesEnabled:
+                    !!this.props.displayConditions || !!this.props.onConditionalsOpen,
             };
 
             this.sendMessage('--config', JSON.parse(JSON.stringify(configData)));
@@ -434,6 +517,8 @@ export class UnlayerStore {
             this.onFormSelectCB?.(data?.formId);
         } else if (type === '--calc-field-open') {
             this.onCalcFieldOpenCB?.(data?.usedFormIds ?? []);
+        } else if (type === '--esign-offset-open') {
+            this.openESignOffsetRules(data);
         } else if (type === '--calc-field-select') {
             if (this.onCalcFieldSelectCB) {
                 this.onCalcFieldSelectCB(data?.fieldKeys ?? []);
@@ -478,6 +563,22 @@ export class UnlayerStore {
         this.onMessageCB?.(type, data);
     };
 
+    private openESignOffsetRules = (data?: Partial<UnlayerEventESignOffset>) => {
+        const requestId = data?.requestId;
+
+        if (!requestId) {
+            return;
+        }
+
+        emitESignOffsetRequest({
+            value: normalizeESignOffsetSettings(data.value),
+            done: value => {
+                const result: UnlayerEventESignOffset = { requestId, value };
+                this.sendMessage('--esign-offset-result', JSON.parse(JSON.stringify(result)));
+            },
+        });
+    };
+
     private updateFormFieldSamples = (formId: number, fields: FormFieldInfo[]) => {
         fields.forEach((field, index) => {
             const normalizedFieldId = String(field.id ?? '').replaceAll('-', '');