@servicetitan/dte-pdf-editor 1.45.0 → 1.47.0

package/src/utils/formula/__tests__/form-fields.utils.test.ts

@@ -0,0 +1,274 @@
+import {
+    DataPointOption,
+    FieldTypeEnum,
+    FormFieldInfo,
+    FormFieldsByFormIdI,
+    FormInfo,
+} from '../../../interface/types';
+import {
+    buildFormFieldKey,
+    buildFormFieldSnapshot,
+    formFieldInfoToFieldTypeOption,
+    formFieldInfosToCalculationOptions,
+    formFieldToDisplayConditionDataPointOption,
+    getDisplayConditionFieldTypeForKey,
+    inferDisplayConditionSourceKind,
+    isFormFieldCalculationType,
+    normalizeFormFieldIdForPath,
+    parseFormFieldKey,
+    tryBuildFormFieldFormulaSnapshot,
+} from '../form-fields.utils';
+
+const buildFormFieldInfo = (overrides: Partial<FormFieldInfo> = {}): FormFieldInfo => ({
+    id: 'abc-123',
+    header: 'My Field',
+    itemType: 'number',
+    ...overrides,
+});
+
+const buildFormInfo = (overrides: Partial<FormInfo> = {}): FormInfo => ({
+    id: 7,
+    name: 'Form A',
+    ...overrides,
+});
+
+describe('normalizeFormFieldIdForPath', () => {
+    test('removes all hyphens from field id', () => {
+        expect(normalizeFormFieldIdForPath('abc-123-def')).toBe('abc123def');
+    });
+
+    test('returns id unchanged when no hyphens are present', () => {
+        expect(normalizeFormFieldIdForPath('abc123')).toBe('abc123');
+    });
+});
+
+describe('buildFormFieldKey', () => {
+    test('builds __submission_fields path with normalized field id', () => {
+        expect(buildFormFieldKey(7, 'abc-123')).toBe('__submission_fields.7.abc123');
+    });
+});
+
+describe('parseFormFieldKey', () => {
+    const subject = (key: string) => parseFormFieldKey(key);
+
+    test('parses canonical __submission_fields path', () => {
+        expect(subject('__submission_fields.7.abc123')).toEqual({
+            formId: 7,
+            fieldId: 'abc123',
+        });
+    });
+
+    test('parses legacy __submission_field (singular) path with hyphens', () => {
+        expect(subject('__submission_field.7.abc-123')).toEqual({
+            formId: 7,
+            fieldId: 'abc123',
+        });
+    });
+
+    test('parses legacy __form_ path', () => {
+        expect(subject('__form_7_abc123')).toEqual({ formId: 7, fieldId: 'abc123' });
+    });
+
+    test('returns null for unrelated paths', () => {
+        expect(subject('user.name')).toBeNull();
+    });
+});
+
+describe('buildFormFieldSnapshot', () => {
+    test('builds a snapshot from form info and field', () => {
+        expect(buildFormFieldSnapshot(7, 'Form A', buildFormFieldInfo())).toEqual({
+            formId: 7,
+            fieldId: 'abc-123',
+            formName: 'Form A',
+            fieldName: 'My Field',
+            fieldType: 'number',
+        });
+    });
+});
+
+describe('tryBuildFormFieldFormulaSnapshot', () => {
+    const forms: FormInfo[] = [buildFormInfo()];
+    const formFieldsByFormId: FormFieldsByFormIdI = {
+        7: [buildFormFieldInfo()],
+    };
+    const subject = (path: string) =>
+        tryBuildFormFieldFormulaSnapshot(path, forms, formFieldsByFormId);
+
+    test('returns snapshot when form and field exist', () => {
+        const snapshot = subject('__submission_fields.7.abc123');
+        expect(snapshot).toEqual({
+            formId: 7,
+            fieldId: 'abc-123',
+            formName: 'Form A',
+            fieldName: 'My Field',
+            fieldType: 'number',
+        });
+    });
+
+    test('returns undefined when path is not a form field key', () => {
+        expect(subject('user.name')).toBeUndefined();
+    });
+
+    test('returns undefined when form is missing', () => {
+        expect(subject('__submission_fields.99.abc123')).toBeUndefined();
+    });
+
+    test('returns undefined when field id does not match any form field', () => {
+        expect(subject('__submission_fields.7.unknown')).toBeUndefined();
+    });
+});
+
+describe('isFormFieldCalculationType', () => {
+    test.each([
+        ['number', true],
+        ['date', true],
+        ['text', false],
+    ] as const)('returns %s for itemType %s', (itemType, expected) => {
+        expect(isFormFieldCalculationType(itemType)).toBe(expected);
+    });
+});
+
+describe('formFieldInfosToCalculationOptions', () => {
+    test('includes only number and date fields with calculation metadata', () => {
+        const fields: FormFieldInfo[] = [
+            buildFormFieldInfo({ id: 'num', itemType: 'number', header: 'Num' }),
+            buildFormFieldInfo({ id: 'dt', itemType: 'date', header: 'Date' }),
+            buildFormFieldInfo({ id: 'txt', itemType: 'text', header: 'Text' }),
+        ];
+
+        const result = formFieldInfosToCalculationOptions(7, fields, 'Form A');
+
+        expect(result).toHaveLength(2);
+        expect(result.map(r => r.label)).toEqual(['Num', 'Date']);
+        expect(result[0].type).toBe(FieldTypeEnum.forms);
+        expect(result[0].path).toBe('__submission_fields.7.num');
+        expect(result[0].formSnapshot).toEqual(
+            expect.objectContaining({ formId: 7, fieldId: 'num', fieldName: 'Num' }),
+        );
+    });
+});
+
+describe('formFieldInfoToFieldTypeOption', () => {
+    test('omits fieldType for non-calculation fields', () => {
+        const result = formFieldInfoToFieldTypeOption(
+            7,
+            buildFormFieldInfo({ itemType: 'text' }),
+            'Form A',
+        );
+        expect(result.fieldType).toBeUndefined();
+    });
+
+    test('includes fieldType for calculation fields', () => {
+        const result = formFieldInfoToFieldTypeOption(
+            7,
+            buildFormFieldInfo({ itemType: 'date' }),
+            'Form A',
+        );
+        expect(result.fieldType).toBe('date');
+    });
+});
+
+describe('formFieldToDisplayConditionDataPointOption', () => {
+    test.each([
+        ['number', 'number'],
+        ['date', 'string'],
+        ['text', 'string'],
+    ] as const)('maps itemType %s to fieldType %s', (itemType, expected) => {
+        const option = formFieldToDisplayConditionDataPointOption(
+            buildFormInfo(),
+            buildFormFieldInfo({ itemType }),
+        );
+        expect(option.fieldType).toBe(expected);
+    });
+
+    test('uses field header as title and snapshot in option', () => {
+        const option = formFieldToDisplayConditionDataPointOption(
+            buildFormInfo(),
+            buildFormFieldInfo(),
+        );
+        expect(option.title).toBe('My Field');
+        expect(option.fullKey).toBe('__submission_fields.7.abc123');
+        expect(option.formSnapshot).toBeDefined();
+    });
+});
+
+describe('getDisplayConditionFieldTypeForKey', () => {
+    const mergeTagOptions: DataPointOption[] = [
+        { fieldType: 'string', fullKey: 'mt.name', title: 'Name' },
+        { fieldType: 'number', fullKey: 'mt.age', title: 'Age' },
+    ];
+    const fillableOptions: DataPointOption[] = [
+        { fieldType: 'string', fullKey: 'fillable_a_b', title: 'A' },
+    ];
+
+    test('returns fieldType from merge tag options', () => {
+        expect(
+            getDisplayConditionFieldTypeForKey('mt.age', mergeTagOptions, fillableOptions, {}),
+        ).toBe('number');
+    });
+
+    test('returns fieldType from fillable options', () => {
+        expect(
+            getDisplayConditionFieldTypeForKey('fillable_a_b', mergeTagOptions, fillableOptions, {}),
+        ).toBe('string');
+    });
+
+    test('returns number for form field with number itemType', () => {
+        const formFieldsByFormId: FormFieldsByFormIdI = {
+            7: [buildFormFieldInfo({ id: 'num', itemType: 'number' })],
+        };
+        expect(
+            getDisplayConditionFieldTypeForKey(
+                '__submission_fields.7.num',
+                mergeTagOptions,
+                fillableOptions,
+                formFieldsByFormId,
+            ),
+        ).toBe('number');
+    });
+
+    test('returns string for unknown data point key', () => {
+        expect(
+            getDisplayConditionFieldTypeForKey('unknown.path', mergeTagOptions, fillableOptions, {}),
+        ).toBe('string');
+    });
+});
+
+describe('inferDisplayConditionSourceKind', () => {
+    const mergeTagOptions: DataPointOption[] = [
+        { fieldType: 'string', fullKey: 'mt.name', title: 'Name' },
+    ];
+    const fillableOptions: DataPointOption[] = [
+        { fieldType: 'string', fullKey: 'fillable_a_b', title: 'A' },
+    ];
+
+    test('returns null for empty key', () => {
+        expect(inferDisplayConditionSourceKind('', mergeTagOptions, fillableOptions)).toBeNull();
+    });
+
+    test('returns forms for a form field path', () => {
+        expect(
+            inferDisplayConditionSourceKind(
+                '__submission_fields.7.abc',
+                mergeTagOptions,
+                fillableOptions,
+            ),
+        ).toBe(FieldTypeEnum.forms);
+    });
+
+    test('returns fillable for a fillable path', () => {
+        expect(
+            inferDisplayConditionSourceKind('fillable_a_b', mergeTagOptions, fillableOptions),
+        ).toBe(FieldTypeEnum.fillable);
+    });
+
+    test('returns dataModel for a merge tag path', () => {
+        expect(inferDisplayConditionSourceKind('mt.name', mergeTagOptions, fillableOptions)).toBe(
+            FieldTypeEnum.dataModel,
+        );
+    });
+
+    test('returns null for unknown key', () => {
+        expect(inferDisplayConditionSourceKind('unknown', mergeTagOptions, fillableOptions)).toBeNull();
+    });
+});

package/src/utils/formula/__tests__/format-calculated-result.utils.test.ts

@@ -0,0 +1,105 @@
+import {
+    CalculatedFieldFormat,
+    CalculatedFormatForDate,
+    CalculatedFormatForNumber,
+} from '../../../interface/types';
+import { formatCalculatedResult } from '../format-calculated-result.utils';
+
+const baseNumberFormat: CalculatedFormatForNumber = {
+    resultType: 'number',
+    thousandsSeparator: false,
+    decimals: 2,
+    roundingMode: 'round',
+    decimalSeparatorEnabled: false,
+    decimalSeparator: '.',
+    prefixText: '',
+    postfixText: '',
+};
+
+describe('formatCalculatedResult', () => {
+    const subject = (value: number, format: CalculatedFieldFormat | undefined) =>
+        formatCalculatedResult(value, format);
+
+    describe('with non-finite values', () => {
+        test.each([NaN, Infinity, -Infinity])('returns empty string for %p', value => {
+            expect(subject(value, baseNumberFormat)).toBe('');
+        });
+    });
+
+    describe('when format is undefined', () => {
+        test('returns the raw value as string', () => {
+            expect(subject(1234.5, undefined)).toBe('1234.5');
+        });
+    });
+
+    describe('with number formatting', () => {
+        test('rounds to the specified decimals', () => {
+            expect(subject(1.236, { ...baseNumberFormat, decimals: 2 })).toBe('1.24');
+        });
+
+        test('floors when roundingMode is floor', () => {
+            expect(subject(1.999, { ...baseNumberFormat, decimals: 0, roundingMode: 'floor' })).toBe(
+                '1',
+            );
+        });
+
+        test('ceils when roundingMode is ceil', () => {
+            expect(subject(1.001, { ...baseNumberFormat, decimals: 0, roundingMode: 'ceil' })).toBe(
+                '2',
+            );
+        });
+
+        test('adds thousands separator when enabled', () => {
+            expect(
+                subject(1234567.89, {
+                    ...baseNumberFormat,
+                    decimals: 2,
+                    thousandsSeparator: true,
+                }),
+            ).toBe('1,234,567.89');
+        });
+
+        test('skips decimal part when decimals is 0', () => {
+            expect(subject(1234, { ...baseNumberFormat, decimals: 0 })).toBe('1234');
+        });
+
+        test('applies prefix and postfix text', () => {
+            expect(
+                subject(50, {
+                    ...baseNumberFormat,
+                    decimals: 0,
+                    prefixText: '$',
+                    postfixText: ' USD',
+                }),
+            ).toBe('$50 USD');
+        });
+    });
+
+    describe('with date formatting', () => {
+        const baseDateFormat: CalculatedFormatForDate = {
+            resultType: 'date',
+            dateFormat: 'MM/DD/YYYY',
+        };
+
+        // Display range is +/- MAX_DATE_DISPLAY_RANGE_YEARS years from "now",
+        // so use today's date to stay within range.
+        const today = new Date();
+        const todayMs = today.getTime();
+
+        test('formats epoch milliseconds with default tokens', () => {
+            const result = subject(todayMs, baseDateFormat);
+            expect(result).toMatch(/^\d{2}\/\d{2}\/\d{4}$/);
+        });
+
+        test('substitutes all supported date tokens', () => {
+            const year = String(today.getFullYear());
+            const result = subject(todayMs, { resultType: 'date', dateFormat: 'YYYY-YY' });
+            expect(result).toBe(`${year}-${year.slice(-2)}`);
+        });
+
+        test('returns empty string when date is far outside display range', () => {
+            const futureDate = Date.UTC(2100, 0, 1);
+            expect(subject(futureDate, baseDateFormat)).toBe('');
+        });
+    });
+});

package/src/utils/formula/__tests__/render-formula.utils.test.ts

@@ -0,0 +1,43 @@
+import { renderFormulaHtml } from '../render-formula.utils';
+
+describe('renderFormulaHtml', () => {
+    const subject = (expression: string, labelMap: Map<string, string>) =>
+        renderFormulaHtml(expression, labelMap);
+
+    test('returns empty string when expression is blank', () => {
+        expect(subject('   ', new Map())).toBe('');
+    });
+
+    test('renders field tokens as chip spans with label and remove button', () => {
+        const html = subject('userName', new Map([['userName', 'User Name']]));
+        expect(html).toContain('class="dte-formula-chip"');
+        expect(html).toContain('data-field="userName"');
+        expect(html).toContain('data-field-index="0"');
+        expect(html).toContain('User Name');
+        expect(html).toContain('data-field-remove="true"');
+    });
+
+    test('falls back to the field value when label is missing', () => {
+        const html = subject('unknown', new Map());
+        expect(html).toContain('>unknown<');
+    });
+
+    test('increments data-field-index for each field token', () => {
+        const html = subject('a b', new Map());
+        expect(html).toContain('data-field-index="0"');
+        expect(html).toContain('data-field-index="1"');
+    });
+
+    test('escapes special characters in non-field tokens', () => {
+        expect(subject('<', new Map())).toContain('&lt;');
+    });
+
+    test('replaces spaces in non-field tokens with non-breaking spaces', () => {
+        const html = subject('a   b', new Map());
+        expect(html).toContain('&nbsp;&nbsp;&nbsp;');
+    });
+
+    test('returns empty string for whitespace-only expression', () => {
+        expect(subject('   ', new Map())).toBe('');
+    });
+});

package/src/utils/formula/__tests__/validate-formula.utils.test.ts

@@ -0,0 +1,168 @@
+import { StructuredFormula } from '../../../interface/types';
+import { validateFormula } from '../validate-formula.utils';
+
+const f = (tokens: StructuredFormula['tokens']): StructuredFormula => ({ tokens });
+
+describe('validateFormula', () => {
+    const subject = (
+        formula: StructuredFormula | undefined | null,
+        validPaths: Set<string>,
+        knownDateFields?: Set<string>,
+        pathToLabel?: Map<string, string>,
+    ) => validateFormula(formula, validPaths, knownDateFields, pathToLabel);
+
+    describe('when formula is empty', () => {
+        test.each([
+            ['undefined', undefined],
+            ['null', null],
+            ['empty tokens', f([])],
+        ])('returns invalid with empty error for %s', (_, formula) => {
+            const result = subject(formula, new Set());
+            expect(result.valid).toBe(false);
+            expect(result.errors).toEqual(['Formula cannot be empty']);
+        });
+    });
+
+    describe('when formula is valid', () => {
+        test('returns valid for a number-only formula', () => {
+            expect(subject(f([{ type: 'number', value: '42' }]), new Set())).toEqual({
+                valid: true,
+                errors: [],
+            });
+        });
+
+        test('returns valid for a known field reference', () => {
+            const result = subject(
+                f([{ type: 'field', path: 'a.b', fieldType: 'number' }]),
+                new Set(['a.b']),
+            );
+            expect(result.valid).toBe(true);
+        });
+
+        test('returns valid for a balanced expression with operators and parens', () => {
+            const result = subject(
+                f([
+                    { type: 'lparen' },
+                    { type: 'number', value: '1' },
+                    { type: 'operator', value: '+' },
+                    { type: 'number', value: '2' },
+                    { type: 'rparen' },
+                    { type: 'operator', value: '*' },
+                    { type: 'number', value: '3' },
+                ]),
+                new Set(),
+            );
+            expect(result.valid).toBe(true);
+        });
+    });
+
+    describe('when formula is invalid', () => {
+        test('reports unknown field', () => {
+            const result = subject(
+                f([{ type: 'field', path: 'unknown', fieldType: 'number' }]),
+                new Set(),
+            );
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes('Unknown field'))).toBe(true);
+        });
+
+        test('uses pathToLabel for unknown field errors', () => {
+            const result = subject(
+                f([{ type: 'field', path: 'x', fieldType: 'number' }]),
+                new Set(),
+                undefined,
+                new Map([['x', 'My Field']]),
+            );
+            expect(result.errors.some(e => e.includes('My Field'))).toBe(true);
+        });
+
+        test('reports unbalanced opening parenthesis', () => {
+            const result = subject(
+                f([{ type: 'lparen' }, { type: 'number', value: '1' }]),
+                new Set(),
+            );
+            expect(result.errors).toContain('Unbalanced parentheses');
+        });
+
+        test('reports unbalanced closing parenthesis', () => {
+            const result = subject(
+                f([{ type: 'number', value: '1' }, { type: 'rparen' }]),
+                new Set(),
+            );
+            expect(result.errors).toContain('Unbalanced parentheses');
+        });
+
+        test('reports two adjacent operands as missing operator', () => {
+            const result = subject(
+                f([
+                    { type: 'number', value: '1' },
+                    { type: 'number', value: '2' },
+                ]),
+                new Set(),
+            );
+            expect(result.errors).toContain('Operator required between two fields or values');
+        });
+
+        test('reports formula starting with operator', () => {
+            const result = subject(
+                f([
+                    { type: 'operator', value: '+' },
+                    { type: 'number', value: '1' },
+                ]),
+                new Set(),
+            );
+            expect(
+                result.errors.some(e => e.includes('start with an operand')),
+            ).toBe(true);
+        });
+
+        test('reports formula ending with operator', () => {
+            const result = subject(
+                f([
+                    { type: 'number', value: '1' },
+                    { type: 'operator', value: '+' },
+                ]),
+                new Set(),
+            );
+            expect(
+                result.errors.some(e => e.includes('end with an operand')),
+            ).toBe(true);
+        });
+
+        test('reports invalid number value', () => {
+            const result = subject(f([{ type: 'number', value: 'abc' }]), new Set());
+            expect(result.errors.some(e => e.includes('Invalid number'))).toBe(true);
+        });
+    });
+
+    describe('with date field constraints', () => {
+        const dateFieldFormula = (operator: '*' | '/' | '+') =>
+            f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: operator },
+                { type: 'number', value: '1' },
+            ]);
+
+        test.each(['*', '/'] as const)('rejects %s operator with date fields', operator => {
+            const result = subject(dateFieldFormula(operator), new Set(['d']), new Set(['d']));
+            expect(
+                result.errors.some(e => e.includes('Multiply') && e.includes('divide')),
+            ).toBe(true);
+        });
+
+        test('allows + and - with date fields', () => {
+            const result = subject(dateFieldFormula('+'), new Set(['d']), new Set(['d']));
+            expect(result.valid).toBe(true);
+        });
+
+        test('rejects numbers larger than MAX_DATE_CALC_DAYS with date fields', () => {
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '5000' },
+            ]);
+            const result = subject(formula, new Set(['d']), new Set(['d']));
+            expect(result.errors.some(e => e.includes('Number of days cannot exceed'))).toBe(true);
+        });
+    });
+});

package/src/utils/formula/expression.utils.ts

@@ -32,6 +32,50 @@ export function tokensToExpression(formula: StructuredFormula | undefined): stri
         .trim();
 }
 
+/**
+ * Convert StructuredFormula tokens to a human-readable display string.
+ *
+ * Field token label resolution order:
+ *   1. `pathToLabel[path]` — caller-provided override (fillable / data-model labels).
+ *   2. `formSnapshot.fieldName` — embedded form-field label carried on the token.
+ *   3. raw `path` — last-resort fallback.
+ *
+ * Use this for read-only UI surfaces where the formula is shown for context
+ * (overlays, previews) — NOT for round-tripping through `parseExpression`,
+ * which expects paths.
+ */
+export function formulaToDisplayText(
+    formula: StructuredFormula | undefined,
+    pathToLabel?: Map<string, string>,
+): string {
+    if (!formula?.tokens?.length) {
+        return '';
+    }
+    return formula.tokens
+        .map(t => {
+            if (t.type === 'field') {
+                const overrideLabel = pathToLabel?.get(t.path);
+                if (overrideLabel) {
+                    return overrideLabel;
+                }
+                if (t.formSnapshot?.fieldName) {
+                    return t.formSnapshot.fieldName;
+                }
+                return t.path;
+            }
+            if (t.type === 'lparen') {
+                return '(';
+            }
+            if (t.type === 'rparen') {
+                return ')';
+            }
+            return t.value;
+        })
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
 /** Token from tokenizing an expression string (before resolving to FormulaToken) */
 export interface ExpressionPart {
     type: 'field' | 'number' | 'operator' | 'paren' | 'text';

package/src/utils/path/__tests__/generate-e-sign-path.test.ts

@@ -0,0 +1,26 @@
+import { ESignFieldType } from '../../../interface/types';
+import { generateESignPath } from '../generate-e-sign-path';
+
+describe('generateESignPath', () => {
+    const subject = (recipient: string, subType: ESignFieldType) =>
+        generateESignPath(recipient, subType);
+
+    test.each([
+        [ESignFieldType.signature, 'esign_signer1_signature'],
+        [ESignFieldType.initials, 'esign_signer1_initials'],
+        [ESignFieldType.dateSigned, 'esign_signer1_dateSigned'],
+        [ESignFieldType.fullName, 'esign_signer1_fullName'],
+    ])('returns esign_{recipient}_%s path', (subType, expected) => {
+        expect(subject('signer1', subType)).toBe(expected);
+    });
+
+    test('builds path with recipient containing special characters', () => {
+        expect(subject('recipient-1', ESignFieldType.signature)).toBe(
+            'esign_recipient-1_signature',
+        );
+    });
+
+    test('builds path with empty recipient', () => {
+        expect(subject('', ESignFieldType.signature)).toBe('esign__signature');
+    });
+});

package/src/utils/path/__tests__/generate-fillable-path.test.ts

@@ -0,0 +1,17 @@
+import { generateFillablePath } from '../generate-fillable-path';
+
+describe('generateFillablePath', () => {
+    const subject = (recipient: string, name: string) => generateFillablePath(recipient, name);
+
+    test('builds fillable_{recipient}_{name} path', () => {
+        expect(subject('signer1', 'fieldName')).toBe('fillable_signer1_fieldName');
+    });
+
+    test('builds path with empty recipient', () => {
+        expect(subject('', 'fieldName')).toBe('fillable__fieldName');
+    });
+
+    test('builds path with empty name', () => {
+        expect(subject('signer1', '')).toBe('fillable_signer1_');
+    });
+});