@servicetitan/dte-unlayer 0.154.0 → 0.156.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/image-upload-error.ts

@@ -0,0 +1,7 @@
+/** Reject `onImage` with this error to show its message to the user instead of the generic upload failure text. */
+export class ImageUploadError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = 'ImageUploadError';
+    }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './editor';
+export { ImageUploadError } from './image-upload-error';
 export * from './tools';
 export * from './api-core';
 export * from './api-custom-tools';

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/store.ts

@@ -1,8 +1,16 @@
+import { emitESignOffsetRequest } from './e-sign-offset/eSignOffsetController';
+import { ImageUploadError } from './image-upload-error';
 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,
@@ -12,7 +20,11 @@ import {
 } from './shared/forms';
 import { schemaBuildMap, schemaIsDate } from './shared/schema';
 import { unlayerToolsParseTwinKey } from './shared/tools';
-import { unlayerToolsDedupeInstanceIds, unlayerToolsIterate } from './tools';
+import {
+    unlayerToolsDedupeInstanceIds,
+    unlayerToolsIterate,
+    unlayerToolsNormalizeESignOffsets,
+} from './tools';
 import {
     createUnlayerEditor,
     DesignUpdatedEventType,
@@ -220,18 +232,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);
                 });
@@ -487,6 +509,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)));
@@ -494,6 +518,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 ?? []);
@@ -538,6 +564,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('-', '');
@@ -679,8 +721,10 @@ export class UnlayerStore {
             return;
         }
 
-        done({ progress: 0 });
-
+        /*
+         * Unlayer only leaves its "uploading" state when `done` receives a url, so `done` must not be
+         * called before the upload succeeds or after it fails, otherwise the image widget gets stuck.
+         */
         try {
             const { url } = await this.onImageCB(file);
             done({ progress: 100, url });
@@ -688,9 +732,10 @@ export class UnlayerStore {
             logUnlayerError('Image upload failed', error);
             this.onErrorCB?.(
                 'Image upload failed',
-                'Something went wrong while uploading the image. Please try again or select another image.',
+                error instanceof ImageUploadError
+                    ? error.message
+                    : 'Something went wrong while uploading the image. Please try again or select another image.',
             );
-            done({ progress: 100 });
         }
     };
 

package/src/tools.ts

@@ -1,4 +1,11 @@
-import { constGenericsEditor, UnlayerToolMetaData } from './shared/const';
+import {
+    constGenericsEditor,
+    E_SIGN_DATE_SIGNED_OFFSET_TYPE,
+    E_SIGN_DATE_SIGNED_OFFSET_VALUES_KEY,
+    E_SIGN_TOOL_SLUG,
+    UnlayerToolMetaData,
+} from './shared/const';
+import { isESignOffsetSettings, normalizeESignOffsetSettings } from './shared/e-sign-offset';
 import { editIconSvg } from './shared/edit-icon';
 import { generateInstanceId, INSTANCE_ID_TOOL_SLUGS } from './shared/instance-id';
 import { unlayerToolsParseUnitKey } from './shared/tools';
@@ -253,6 +260,34 @@ export const unlayerToolsDedupeInstanceIds = (
     return hasChanges;
 };
 
+/**
+ * Gives every "Date Signed Offset" e-sign placement valid settings. Unlayer never applies an
+ * option's default to placements saved before the option existed, and the backend rejects a
+ * design whose dateSignedOffset recipient has no settings.
+ */
+export const unlayerToolsNormalizeESignOffsets = (design: UnlayerDesignFormat): boolean => {
+    let hasChanges = false;
+
+    unlayerToolsIterateCustom(design, tool => {
+        if (
+            tool.slug !== E_SIGN_TOOL_SLUG ||
+            tool.values?.eSignFieldType !== E_SIGN_DATE_SIGNED_OFFSET_TYPE
+        ) {
+            return;
+        }
+
+        const settings = tool.values[E_SIGN_DATE_SIGNED_OFFSET_VALUES_KEY];
+
+        if (!isESignOffsetSettings(settings)) {
+            tool.values[E_SIGN_DATE_SIGNED_OFFSET_VALUES_KEY] =
+                normalizeESignOffsetSettings(settings);
+            hasChanges = true;
+        }
+    });
+
+    return hasChanges;
+};
+
 export const unlayerToolsBuildDesign = (tools: UnlayerDesignTool[]): UnlayerDesignFormat => {
     const design = unlayerGetDefaultDesign();