@servicetitan/dte-pdf-editor 1.45.0 → 1.47.0

package/src/utils/data-model/__tests__/extract-fields.utils.test.ts

@@ -0,0 +1,154 @@
+import { FieldTypeEnum, SchemaObject } from '../../../interface/types';
+import { extractGroupedFieldsFromDataModel } from '../extract-fields.utils';
+
+const emptySchema: SchemaObject = { type: 'object', properties: {} };
+
+describe('extractGroupedFieldsFromDataModel', () => {
+    const subject = (
+        schema: SchemaObject,
+        options?: Parameters<typeof extractGroupedFieldsFromDataModel>[1],
+    ) => extractGroupedFieldsFromDataModel(schema, options);
+
+    describe('when schema has no properties', () => {
+        test('returns empty array', () => {
+            expect(subject(emptySchema)).toEqual([]);
+        });
+    });
+
+    describe('with top-level simple fields', () => {
+        const schema: SchemaObject = {
+            type: 'object',
+            properties: {
+                firstName: { type: 'string', title: 'First Name' },
+                age: { type: 'number' },
+            },
+        };
+
+        test('groups simple fields under the default "Fields" group', () => {
+            const result = subject(schema);
+            expect(result).toHaveLength(1);
+            expect(result[0].groupName).toBe('Fields');
+            expect(result[0].fields).toEqual([
+                {
+                    label: 'First Name',
+                    type: FieldTypeEnum.dataModel,
+                    path: 'firstName',
+                    fieldType: undefined,
+                },
+                {
+                    label: 'age',
+                    type: FieldTypeEnum.dataModel,
+                    path: 'age',
+                    fieldType: 'number',
+                },
+            ]);
+        });
+    });
+
+    describe('with object properties', () => {
+        const schema: SchemaObject = {
+            type: 'object',
+            properties: {
+                user: {
+                    type: 'object',
+                    title: 'User Info',
+                    properties: {
+                        name: { type: 'string', title: 'Name' },
+                        address: {
+                            type: 'object',
+                            properties: {
+                                city: { type: 'string', title: 'City' },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+
+        test('flattens nested object properties into one group per top-level object', () => {
+            const result = subject(schema);
+            expect(result).toHaveLength(1);
+            expect(result[0].groupName).toBe('User Info');
+            expect(result[0].fields).toEqual([
+                {
+                    label: 'Name',
+                    type: FieldTypeEnum.dataModel,
+                    path: 'user.name',
+                    fieldType: undefined,
+                },
+                {
+                    label: 'City',
+                    type: FieldTypeEnum.dataModel,
+                    path: 'user.address.city',
+                    fieldType: undefined,
+                },
+            ]);
+        });
+    });
+
+    test('places default-group fields before object groups', () => {
+        const schema: SchemaObject = {
+            type: 'object',
+            properties: {
+                top: { type: 'string' },
+                user: {
+                    type: 'object',
+                    title: 'User',
+                    properties: { name: { type: 'string' } },
+                },
+            },
+        };
+        const result = subject(schema);
+        expect(result.map(g => g.groupName)).toEqual(['Fields', 'User']);
+    });
+
+    test('skips array properties', () => {
+        const schema: SchemaObject = {
+            type: 'object',
+            properties: {
+                items: { type: 'array', items: { type: 'string' } },
+            },
+        };
+        expect(subject(schema)).toEqual([]);
+    });
+
+    test('skips empty object groups', () => {
+        const schema: SchemaObject = {
+            type: 'object',
+            properties: {
+                empty: { type: 'object', properties: {} },
+            },
+        };
+        expect(subject(schema)).toEqual([]);
+    });
+
+    describe('with onlyUseInCalculatedFields option', () => {
+        const schema: SchemaObject = {
+            type: 'object',
+            properties: {
+                included: {
+                    type: 'number',
+                    options: { useInCalculatedFields: true },
+                },
+                excluded: { type: 'number' },
+                user: {
+                    type: 'object',
+                    title: 'User',
+                    properties: {
+                        salary: {
+                            type: 'number',
+                            options: { useInCalculatedFields: true },
+                        },
+                        notes: { type: 'string' },
+                    },
+                },
+            },
+        };
+
+        test('keeps only fields flagged with useInCalculatedFields', () => {
+            const result = subject(schema, { onlyUseInCalculatedFields: true });
+            const allPaths = result.flatMap(g => g.fields.map(f => f.path));
+            expect(allPaths.sort()).toEqual(['included', 'user.salary']);
+        });
+    });
+});

package/src/utils/data-model/__tests__/resolve-values.utils.test.ts

@@ -0,0 +1,60 @@
+import { DataModelValues } from '../../../interface/types';
+import { resolvePdfDataValues } from '../resolve-values.utils';
+
+describe('resolvePdfDataValues', () => {
+    const subject = (data: DataModelValues | undefined, path: string | undefined) =>
+        resolvePdfDataValues(data, path);
+
+    describe('when data or path are missing', () => {
+        test.each([
+            ['data is undefined', undefined, 'some.path'],
+            ['path is undefined', { foo: 'bar' }, undefined],
+            ['path is empty', { foo: 'bar' }, ''],
+        ])('returns empty string when %s', (_, data, path) => {
+            expect(subject(data as DataModelValues | undefined, path)).toBe('');
+        });
+    });
+
+    describe('with primitive resolution', () => {
+        test('resolves a top-level string property', () => {
+            expect(subject({ name: 'John' }, 'name')).toBe('John');
+        });
+
+        test('resolves a nested string property', () => {
+            expect(subject({ user: { name: 'John' } }, 'user.name')).toBe('John');
+        });
+
+        test('resolves a numeric property as string', () => {
+            expect(subject({ count: 42 }, 'count')).toBe('42');
+        });
+
+        test('resolves a boolean property as string', () => {
+            expect(subject({ active: true }, 'active')).toBe('true');
+        });
+    });
+
+    describe('when value is missing', () => {
+        test.each([
+            ['null value', { user: null }, 'user.name'],
+            ['undefined value', { user: undefined }, 'user.name'],
+            ['unknown key', { user: { name: 'John' } }, 'user.email'],
+            ['intermediate value is not object', { user: 'string' }, 'user.name'],
+        ])('returns empty string for %s', (_, data, path) => {
+            expect(subject(data as DataModelValues, path)).toBe('');
+        });
+    });
+
+    describe('with object value resolution', () => {
+        test('formats amount/currency objects', () => {
+            expect(subject({ price: { Amount: 100, Currency: 'USD' } }, 'price')).toBe('USD 100');
+        });
+
+        test('returns Value property when present', () => {
+            expect(subject({ field: { Value: 'inner' } }, 'field')).toBe('inner');
+        });
+
+        test('stringifies generic objects via JSON', () => {
+            expect(subject({ obj: { foo: 'bar' } }, 'obj')).toBe('{"foo":"bar"}');
+        });
+    });
+});

package/src/utils/field/__tests__/field-background-color.utils.test.ts

@@ -0,0 +1,26 @@
+import { getFieldBackgroundColor } from '../field-background-color.utils';
+
+describe('getFieldBackgroundColor', () => {
+    const subject = (recipient: string | undefined, recipientsColors: Record<string, string>) =>
+        getFieldBackgroundColor(recipient, recipientsColors);
+
+    test('returns color for recipient when present in map', () => {
+        expect(subject('signer1', { signer1: '#ff0000', signer2: '#00ff00' })).toBe('#ff0000');
+    });
+
+    test('returns "none" when recipient is undefined', () => {
+        expect(subject(undefined, { signer1: '#ff0000' })).toBe('none');
+    });
+
+    test('returns "none" when recipient is empty string', () => {
+        expect(subject('', { signer1: '#ff0000' })).toBe('none');
+    });
+
+    test('returns "none" when recipient is not in the color map', () => {
+        expect(subject('unknown', { signer1: '#ff0000' })).toBe('none');
+    });
+
+    test('returns "none" when color map is empty', () => {
+        expect(subject('signer1', {})).toBe('none');
+    });
+});

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