@servicetitan/dte-pdf-editor 1.45.0 → 1.46.0

package/src/utils/field/__tests__/field-placeholder-text.utils.test.ts

@@ -0,0 +1,46 @@
+import { FieldTypeEnum, PdfField } from '../../../interface/types';
+import { getFieldPlaceholderText } from '../field-placeholder-text.utils';
+
+const buildField = (overrides: Partial<PdfField> = {}): PdfField => ({
+    id: 'field-1',
+    type: FieldTypeEnum.fillable,
+    x: 0,
+    y: 0,
+    page: 1,
+    label: 'Field Label',
+    width: 100,
+    height: 25,
+    ...overrides,
+});
+
+describe('getFieldPlaceholderText', () => {
+    const subject = (field: PdfField, prefix?: string) => getFieldPlaceholderText(field, prefix);
+
+    test('returns label when no prefix and not required', () => {
+        expect(subject(buildField())).toBe('Field Label');
+    });
+
+    test('appends asterisk when field is required', () => {
+        expect(subject(buildField({ required: true }))).toBe('Field Label *');
+    });
+
+    test('prepends prefix when provided', () => {
+        expect(subject(buildField(), 'Enter')).toBe('Enter Field Label');
+    });
+
+    test('joins prefix, label, and required asterisk in order', () => {
+        expect(subject(buildField({ required: true }), 'Enter')).toBe('Enter Field Label *');
+    });
+
+    test('skips empty label', () => {
+        expect(subject(buildField({ label: '' }), 'Enter')).toBe('Enter');
+    });
+
+    test('returns required asterisk only when label is empty and required', () => {
+        expect(subject(buildField({ label: '', required: true }))).toBe('*');
+    });
+
+    test('returns empty string when label is empty, not required, and no prefix', () => {
+        expect(subject(buildField({ label: '' }))).toBe('');
+    });
+});

package/src/utils/formula/__tests__/dom.utils.test.ts

@@ -0,0 +1,33 @@
+import { escapeHtml } from '../dom.utils';
+
+describe('escapeHtml', () => {
+    const subject = (value: string) => escapeHtml(value);
+
+    test.each([
+        ['<', '&lt;'],
+        ['>', '&gt;'],
+        ['&', '&amp;'],
+        ['"', '&quot;'],
+        ["'", '&#039;'],
+    ])('escapes %s to %s', (value, expected) => {
+        expect(subject(value)).toBe(expected);
+    });
+
+    test('escapes a typical HTML snippet', () => {
+        expect(subject('<div class="x">A & B</div>')).toBe(
+            '&lt;div class=&quot;x&quot;&gt;A &amp; B&lt;/div&gt;',
+        );
+    });
+
+    test('returns plain string unchanged', () => {
+        expect(subject('Hello world')).toBe('Hello world');
+    });
+
+    test('returns empty string for empty input', () => {
+        expect(subject('')).toBe('');
+    });
+
+    test('escapes ampersand first to avoid double encoding', () => {
+        expect(subject('&lt;')).toBe('&amp;lt;');
+    });
+});

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

@@ -0,0 +1,202 @@
+import { DataModelValues, StructuredFormula } from '../../../interface/types';
+import { evaluateFormula, valueToNumber } from '../evaluate-formula.utils';
+
+const f = (tokens: StructuredFormula['tokens']): StructuredFormula => ({ tokens });
+
+describe('valueToNumber', () => {
+    const subject = (raw: unknown) => valueToNumber(raw);
+
+    test.each([
+        ['null', null, 0],
+        ['undefined', undefined, 0],
+        ['empty string', '', 0],
+        ['whitespace', '   ', 0],
+        ['NaN', NaN, 0],
+        ['non-numeric string', 'abc', 0],
+        ['boolean', true, 0],
+    ])('returns 0 for %s', (_, raw, expected) => {
+        expect(subject(raw)).toBe(expected);
+    });
+
+    test.each([
+        ['integer', 42, 42],
+        ['negative integer', -5, -5],
+        ['float', 3.14, 3.14],
+        ['integer string', '42', 42],
+        ['float string', '3.14', 3.14],
+        ['string with whitespace', '  42  ', 42],
+    ])('returns numeric value for %s', (_, raw, expected) => {
+        expect(subject(raw)).toBe(expected);
+    });
+});
+
+describe('evaluateFormula', () => {
+    const subject = (
+        formula: StructuredFormula | undefined | null,
+        data: DataModelValues | undefined,
+        holidays?: string[],
+    ) => evaluateFormula(formula, data, holidays);
+
+    describe('when formula is empty', () => {
+        test.each([
+            ['undefined', undefined],
+            ['null', null],
+            ['empty tokens', f([])],
+        ])('returns null for %s', (_, formula) => {
+            expect(subject(formula, {})).toBeNull();
+        });
+    });
+
+    describe('with numeric arithmetic', () => {
+        test.each([
+            [
+                'addition',
+                f([
+                    { type: 'number', value: '1' },
+                    { type: 'operator', value: '+' },
+                    { type: 'number', value: '2' },
+                ]),
+                3,
+            ],
+            [
+                'subtraction',
+                f([
+                    { type: 'number', value: '10' },
+                    { type: 'operator', value: '-' },
+                    { type: 'number', value: '3' },
+                ]),
+                7,
+            ],
+            [
+                'multiplication',
+                f([
+                    { type: 'number', value: '4' },
+                    { type: 'operator', value: '*' },
+                    { type: 'number', value: '5' },
+                ]),
+                20,
+            ],
+            [
+                'division',
+                f([
+                    { type: 'number', value: '20' },
+                    { type: 'operator', value: '/' },
+                    { type: 'number', value: '4' },
+                ]),
+                5,
+            ],
+        ])('evaluates %s', (_, formula, expected) => {
+            expect(subject(formula, {})).toBe(expected);
+        });
+
+        test('returns 0 for division by zero', () => {
+            const formula = f([
+                { type: 'number', value: '10' },
+                { type: 'operator', value: '/' },
+                { type: 'number', value: '0' },
+            ]);
+            expect(subject(formula, {})).toBe(0);
+        });
+
+        test('honors operator precedence (multiply before add)', () => {
+            const formula = f([
+                { type: 'number', value: '1' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '2' },
+                { type: 'operator', value: '*' },
+                { type: 'number', value: '3' },
+            ]);
+            expect(subject(formula, {})).toBe(7);
+        });
+
+        test('respects parentheses', () => {
+            const formula = f([
+                { type: 'lparen' },
+                { type: 'number', value: '1' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '2' },
+                { type: 'rparen' },
+                { type: 'operator', value: '*' },
+                { type: 'number', value: '3' },
+            ]);
+            expect(subject(formula, {})).toBe(9);
+        });
+    });
+
+    describe('with field references', () => {
+        test('resolves field values from data', () => {
+            const formula = f([
+                { type: 'field', path: 'a', fieldType: 'number' },
+                { type: 'operator', value: '+' },
+                { type: 'field', path: 'b', fieldType: 'number' },
+            ]);
+            expect(subject(formula, { a: 5, b: 7 })).toBe(12);
+        });
+
+        test('returns null when any field value is missing', () => {
+            const formula = f([
+                { type: 'field', path: 'a', fieldType: 'number' },
+                { type: 'operator', value: '+' },
+                { type: 'field', path: 'b', fieldType: 'number' },
+            ]);
+            expect(subject(formula, { a: 5 })).toBeNull();
+        });
+
+        test('returns null when a field value is not numeric', () => {
+            const formula = f([
+                { type: 'field', path: 'a', fieldType: 'number' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '1' },
+            ]);
+            expect(subject(formula, { a: 'not a number' })).toBeNull();
+        });
+    });
+
+    describe('with date fields', () => {
+        test('adds business days to a date field (skipping weekend)', () => {
+            // Friday 2024-01-05 + 1 business day = Monday 2024-01-08
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '1' },
+            ]);
+            const result = subject(formula, { d: '2024-01-05' });
+            expect(result).not.toBeNull();
+            const date = new Date(result as number);
+            expect(date.getUTCFullYear()).toBe(2024);
+            expect(date.getUTCMonth()).toBe(0);
+            expect(date.getUTCDate()).toBe(8);
+        });
+
+        test('counts business days when subtracting later date from earlier date', () => {
+            // start - end traverses Mon 2024-01-01 → Fri 2024-01-05 = 4 business days
+            const formula = f([
+                { type: 'field', path: 'start', fieldType: 'date' },
+                { type: 'operator', value: '-' },
+                { type: 'field', path: 'end', fieldType: 'date' },
+            ]);
+            expect(subject(formula, { start: '2024-01-01', end: '2024-01-05' })).toBe(4);
+        });
+
+        test('skips holidays when adding business days', () => {
+            // Monday 2024-01-08 + 1 day skips holiday 2024-01-09 = Wednesday 2024-01-10
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '1' },
+            ]);
+            const result = subject(formula, { d: '2024-01-08' }, ['2024-01-09']);
+            expect(result).not.toBeNull();
+            expect(new Date(result as number).getUTCDate()).toBe(10);
+        });
+
+        test('returns null when date field has invalid value', () => {
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '1' },
+            ]);
+            expect(subject(formula, { d: 'not-a-date' })).toBeNull();
+        });
+    });
+});

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

@@ -0,0 +1,119 @@
+import { StructuredFormula } from '../../../interface/types';
+import {
+    normalizeMergeTags,
+    parseExpression,
+    tokenizeExpression,
+    tokensToExpression,
+} from '../expression.utils';
+
+describe('tokensToExpression', () => {
+    const subject = (formula: StructuredFormula | undefined) => tokensToExpression(formula);
+
+    test('returns empty string when formula is undefined', () => {
+        expect(subject(undefined)).toBe('');
+    });
+
+    test('returns empty string when tokens array is empty', () => {
+        expect(subject({ tokens: [] })).toBe('');
+    });
+
+    test('serializes a mix of token types separated by spaces', () => {
+        const formula: StructuredFormula = {
+            tokens: [
+                { type: 'lparen' },
+                { type: 'field', path: 'a.b', fieldType: 'number' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '5' },
+                { type: 'rparen' },
+                { type: 'operator', value: '*' },
+                { type: 'number', value: '2' },
+            ],
+        };
+        expect(subject(formula)).toBe('( a.b + 5 ) * 2');
+    });
+});
+
+describe('tokenizeExpression', () => {
+    const subject = (expression: string) => tokenizeExpression(expression);
+
+    test('returns empty array for empty input', () => {
+        expect(subject('')).toEqual([]);
+    });
+
+    test('tokenizes identifiers with dots and hyphens as fields', () => {
+        expect(subject('user.name-id')).toEqual([{ type: 'field', value: 'user.name-id' }]);
+    });
+
+    test('tokenizes numbers including decimals', () => {
+        expect(subject('3.14 42')).toEqual([
+            { type: 'number', value: '3.14' },
+            { type: 'text', value: ' ' },
+            { type: 'number', value: '42' },
+        ]);
+    });
+
+    test('tokenizes operators and parens', () => {
+        const result = subject('(a + b)');
+        expect(result.filter(t => t.type === 'paren').map(t => t.value)).toEqual(['(', ')']);
+        expect(result.filter(t => t.type === 'operator').map(t => t.value)).toEqual(['+']);
+    });
+});
+
+describe('parseExpression', () => {
+    const subject = (
+        expression: string,
+        validPaths: Set<string>,
+        knownDateFields?: Set<string>,
+    ) => parseExpression(expression, validPaths, knownDateFields);
+
+    test('drops unknown field identifiers', () => {
+        const validPaths = new Set(['known.path']);
+        const tokens = subject('known.path + unknown + 1', validPaths);
+        expect(tokens).toEqual([
+            { type: 'field', path: 'known.path', fieldType: 'number' },
+            { type: 'operator', value: '+' },
+            { type: 'operator', value: '+' },
+            { type: 'number', value: '1' },
+        ]);
+    });
+
+    test('marks known date fields with fieldType date', () => {
+        const tokens = subject(
+            'a.date + 1',
+            new Set(['a.date']),
+            new Set(['a.date']),
+        );
+        expect(tokens[0]).toEqual({ type: 'field', path: 'a.date', fieldType: 'date' });
+    });
+
+    test('parses parentheses to lparen/rparen tokens', () => {
+        const tokens = subject('( 1 + 2 )', new Set());
+        expect(tokens.map(t => t.type)).toEqual([
+            'lparen',
+            'number',
+            'operator',
+            'number',
+            'rparen',
+        ]);
+    });
+});
+
+describe('normalizeMergeTags', () => {
+    const subject = (expression: string, validPaths: Set<string>) =>
+        normalizeMergeTags(expression, validPaths);
+
+    test('returns input unchanged when validPaths is empty', () => {
+        expect(subject('a b', new Set())).toEqual({ normalized: 'a b', removed: null });
+    });
+
+    test('returns input unchanged when no adjacent merge tags exist', () => {
+        const result = subject('a + b', new Set(['a', 'b']));
+        expect(result).toEqual({ normalized: 'a + b', removed: null });
+    });
+
+    test('removes the left tag when two valid tags are adjacent without separator', () => {
+        const result = subject('ab', new Set(['a', 'b']));
+        expect(result.normalized).toBe('b');
+        expect(result.removed).toEqual({ start: 0, end: 1 });
+    });
+});

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