@servicetitan/dte-pdf-editor 1.44.0 → 1.46.0

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/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_');
+    });
+});

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

@@ -0,0 +1,25 @@
+import { parseFillablePathName } from '../parse-fillable-path';
+
+describe('parseFillablePathName', () => {
+    const subject = (path: string | undefined) => parseFillablePathName(path);
+
+    test.each([
+        ['fillable_signer1_fieldName', 'fieldName'],
+        ['fillable_signer1_', ''],
+        ['fillable_signer1_some_uuid_with_underscores', 'some'],
+    ])('parses "%s" to "%s"', (path, expected) => {
+        expect(subject(path)).toBe(expected);
+    });
+
+    test('returns empty string for undefined path', () => {
+        expect(subject(undefined)).toBe('');
+    });
+
+    test('returns empty string for empty path', () => {
+        expect(subject('')).toBe('');
+    });
+
+    test('returns empty string when path has fewer than 3 parts', () => {
+        expect(subject('fillable_signer1')).toBe('');
+    });
+});

package/src/utils/recipients/__tests__/map-colors.test.ts

@@ -0,0 +1,40 @@
+import { RecipientInfo } from '../../../interface/types';
+import { mapColorsToRecipients } from '../map-colors';
+
+const buildRecipient = (id: number, name: string): RecipientInfo => ({
+    id,
+    name,
+    displayName: name,
+});
+
+describe('mapColorsToRecipients', () => {
+    const subject = (recipients?: RecipientInfo[]) => mapColorsToRecipients(recipients);
+
+    test('returns empty object when recipients is undefined', () => {
+        expect(subject(undefined)).toEqual({});
+    });
+
+    test('returns empty object when recipients is empty', () => {
+        expect(subject([])).toEqual({});
+    });
+
+    test('maps each recipient name to a distinct color', () => {
+        const recipients = [
+            buildRecipient(1, 'recipient_a'),
+            buildRecipient(2, 'recipient_b'),
+            buildRecipient(3, 'recipient_c'),
+        ];
+
+        const result = subject(recipients);
+
+        expect(Object.keys(result)).toEqual(['recipient_a', 'recipient_b', 'recipient_c']);
+        expect(new Set(Object.values(result)).size).toBe(3);
+    });
+
+    test('uses last recipient color when names collide', () => {
+        const result = subject([buildRecipient(1, 'duplicate'), buildRecipient(2, 'duplicate')]);
+
+        expect(Object.keys(result)).toEqual(['duplicate']);
+        expect(result.duplicate).toBeDefined();
+    });
+});

package/src/utils/shared/__tests__/date.utils.test.ts

@@ -0,0 +1,58 @@
+import { dateToUtcZero, toDateInputValue } from '../date.utils';
+
+describe('dateToUtcZero', () => {
+    const subject = (dateString: string) => dateToUtcZero(dateString);
+
+    test('converts YYYY-MM-DD string to UTC midnight ISO string', () => {
+        expect(subject('2024-01-15')).toBe('2024-01-15T00:00:00.000Z');
+    });
+
+    test('handles single-digit month and day', () => {
+        expect(subject('2024-03-05')).toBe('2024-03-05T00:00:00.000Z');
+    });
+
+    test('handles end of year dates', () => {
+        expect(subject('2024-12-31')).toBe('2024-12-31T00:00:00.000Z');
+    });
+
+    test('handles leap year dates', () => {
+        expect(subject('2024-02-29')).toBe('2024-02-29T00:00:00.000Z');
+    });
+});
+
+describe('toDateInputValue', () => {
+    const subject = (value: unknown) => toDateInputValue(value);
+
+    test.each([
+        ['null', null],
+        ['undefined', undefined],
+        ['empty string', ''],
+    ])('returns empty string for %s', (_, value) => {
+        expect(subject(value)).toBe('');
+    });
+
+    test('returns ISO date portion for valid Date object', () => {
+        const date = new Date(Date.UTC(2024, 0, 15, 12, 0, 0));
+        expect(subject(date)).toBe('2024-01-15');
+    });
+
+    test('returns empty string for invalid Date object', () => {
+        expect(subject(new Date('not-a-date'))).toBe('');
+    });
+
+    test('returns first 10 characters of an ISO date string', () => {
+        expect(subject('2024-01-15T12:30:00.000Z')).toBe('2024-01-15');
+    });
+
+    test('returns first 10 characters of a YYYY-MM-DD string as-is', () => {
+        expect(subject('2024-01-15')).toBe('2024-01-15');
+    });
+
+    test.each([
+        ['number', 12345],
+        ['boolean', true],
+        ['object', { foo: 'bar' }],
+    ])('returns empty string for unsupported %s value', (_, value) => {
+        expect(subject(value)).toBe('');
+    });
+});

package/src/utils/shared/__tests__/number.utils.test.ts

@@ -0,0 +1,48 @@
+import { isValidNumber } from '../number.utils';
+
+describe('isValidNumber', () => {
+    const subject = (value: string | number) => isValidNumber(value);
+
+    describe('with numeric input', () => {
+        test.each([
+            [0, true],
+            [1, true],
+            [-1, true],
+            [3.14, true],
+            [Number.MAX_SAFE_INTEGER, true],
+        ])('returns true for finite number %p', (value, expected) => {
+            expect(subject(value)).toBe(expected);
+        });
+
+        test.each([
+            [NaN, false],
+            [Infinity, false],
+            [-Infinity, false],
+        ])('returns false for non-finite number %p', (value, expected) => {
+            expect(subject(value)).toBe(expected);
+        });
+    });
+
+    describe('with string input', () => {
+        test.each([
+            ['0', true],
+            ['1', true],
+            ['-1', true],
+            ['3.14', true],
+            ['  42  ', true],
+            ['1e3', true],
+        ])('returns true for parseable string %p', (value, expected) => {
+            expect(subject(value)).toBe(expected);
+        });
+
+        test.each([
+            ['', false],
+            ['   ', false],
+            ['abc', false],
+            ['1.2.3', false],
+            ['NaN', false],
+        ])('returns false for non-numeric string %p', (value, expected) => {
+            expect(subject(value)).toBe(expected);
+        });
+    });
+});

package/src/utils/shared/date.utils.ts

@@ -4,3 +4,19 @@ export const dateToUtcZero = (dateString: string): string => {
 
     return utcDate.toISOString();
 };
+
+export const toDateInputValue = (value: unknown): string => {
+    if (value == null || value === '') {
+        return '';
+    }
+
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? '' : value.toISOString().slice(0, 10);
+    }
+
+    if (typeof value === 'string') {
+        return value.slice(0, 10);
+    }
+
+    return '';
+};