@servicetitan/dte-pdf-editor 1.44.0 → 1.46.0

package/src/__tests__/field-types/form-fields.test.ts

@@ -0,0 +1,193 @@
+import {
+    FieldTypeEnum,
+    FormFieldInfo,
+    FormFieldsByFormIdI,
+    FormInfo,
+    StructuredFormula,
+} from '../../interface/types';
+import {
+    buildFormFieldKey,
+    evaluateFormula,
+    formFieldInfoToFieldTypeOption,
+    formFieldInfosToCalculationOptions,
+    formFieldToDisplayConditionDataPointOption,
+    normalizeFormFieldIdForPath,
+    parseFormFieldKey,
+    tryBuildFormFieldFormulaSnapshot,
+} from '../../utils';
+
+/**
+ * Scenario tests for form submission fields.
+ *
+ * Form fields belong to a referenced submission form and are addressed by
+ * the path `__submission_fields.{formId}.{normalizedFieldId}`. Field IDs
+ * contain hyphens that are stripped when building the path so it survives
+ * nunjucks templating. Legacy formats (`__submission_field` singular and
+ * `__form_{id}_{hex}`) must still parse for back-compat.
+ */
+
+const form: FormInfo = { id: 7, name: 'Customer Intake' };
+
+const formFields: FormFieldInfo[] = [
+    { id: 'score-uuid-1', header: 'Score', itemType: 'number' },
+    { id: 'when-uuid-2', header: 'When', itemType: 'date' },
+    { id: 'note-uuid-3', header: 'Note', itemType: 'text' },
+];
+
+const formFieldsByFormId: FormFieldsByFormIdI = { 7: formFields };
+
+describe('form field scenarios', () => {
+    describe('with key generation and parsing', () => {
+        test('normalizes hyphenated field IDs', () => {
+            expect(normalizeFormFieldIdForPath('abc-123-def')).toBe('abc123def');
+        });
+
+        test('builds __submission_fields path with normalized id', () => {
+            expect(buildFormFieldKey(form.id, 'score-uuid-1')).toBe(
+                '__submission_fields.7.scoreuuid1',
+            );
+        });
+
+        test.each([
+            [
+                'canonical path',
+                '__submission_fields.7.scoreuuid1',
+                { formId: 7, fieldId: 'scoreuuid1' },
+            ],
+            [
+                'legacy singular path (hyphens stripped)',
+                '__submission_field.7.score-uuid-1',
+                { formId: 7, fieldId: 'scoreuuid1' },
+            ],
+            [
+                'legacy __form_ path',
+                '__form_7_abc123',
+                { formId: 7, fieldId: 'abc123' },
+            ],
+        ])('parses %s', (_, key, expected) => {
+            expect(parseFormFieldKey(key)).toEqual(expected);
+        });
+
+        test('returns null for non-form keys', () => {
+            expect(parseFormFieldKey('Customer.Name')).toBeNull();
+        });
+    });
+
+    describe('with calculation options', () => {
+        const subject = () =>
+            formFieldInfosToCalculationOptions(form.id, formFields, form.name);
+
+        test('includes only number and date fields', () => {
+            expect(subject().map(o => o.label)).toEqual(['Score', 'When']);
+        });
+
+        test('marks each calculation option with the forms field type', () => {
+            expect(subject().every(o => o.type === FieldTypeEnum.forms)).toBe(true);
+        });
+
+        test('attaches form snapshot to each calculation option', () => {
+            expect(subject()[0].formSnapshot).toEqual({
+                formId: 7,
+                fieldId: 'score-uuid-1',
+                formName: 'Customer Intake',
+                fieldName: 'Score',
+                fieldType: 'number',
+            });
+        });
+    });
+
+    describe('with sidebar field options', () => {
+        test('includes text fields without a fieldType', () => {
+            const option = formFieldInfoToFieldTypeOption(form.id, formFields[2], form.name);
+            expect(option.label).toBe('Note');
+            expect(option.fieldType).toBeUndefined();
+        });
+
+        test('includes calculation type for numeric fields', () => {
+            const option = formFieldInfoToFieldTypeOption(form.id, formFields[0], form.name);
+            expect(option.fieldType).toBe('number');
+        });
+    });
+
+    describe('with display-condition data points', () => {
+        test.each([
+            ['number', formFields[0], 'number'],
+            ['date', formFields[1], 'string'],
+            ['text', formFields[2], 'string'],
+        ] as const)(
+            'maps %s field to display-condition fieldType %s',
+            (_, field, expectedType) => {
+                const option = formFieldToDisplayConditionDataPointOption(form, field);
+                expect(option.fieldType).toBe(expectedType);
+            },
+        );
+
+        test('uses field header as the display title', () => {
+            const option = formFieldToDisplayConditionDataPointOption(form, formFields[0]);
+            expect(option.title).toBe('Score');
+        });
+
+        test('includes form snapshot for safe rendering', () => {
+            const option = formFieldToDisplayConditionDataPointOption(form, formFields[0]);
+            expect(option.formSnapshot).toEqual({
+                formId: 7,
+                fieldId: 'score-uuid-1',
+                formName: 'Customer Intake',
+                fieldName: 'Score',
+                fieldType: 'number',
+            });
+        });
+    });
+
+    describe('with formula snapshots resolved from path', () => {
+        const subject = (path: string) =>
+            tryBuildFormFieldFormulaSnapshot(path, [form], formFieldsByFormId);
+
+        test('returns snapshot for known form field path', () => {
+            expect(subject('__submission_fields.7.scoreuuid1')).toEqual({
+                formId: 7,
+                fieldId: 'score-uuid-1',
+                formName: 'Customer Intake',
+                fieldName: 'Score',
+                fieldType: 'number',
+            });
+        });
+
+        test.each([
+            ['unrelated path', 'Customer.Name'],
+            ['unknown form', '__submission_fields.99.abc123'],
+            ['unknown field id', '__submission_fields.7.unknownid'],
+        ])('returns undefined for %s', (_, path) => {
+            expect(subject(path)).toBeUndefined();
+        });
+    });
+
+    describe('with form fields evaluated in a formula at runtime', () => {
+        const scoreKey = buildFormFieldKey(7, 'score-uuid-1');
+
+        test('reads numeric form field via __submission_fields path', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: scoreKey, fieldType: 'number' },
+                    { type: 'operator', value: '*' },
+                    { type: 'number', value: '2' },
+                ],
+            };
+            const data = {
+                __submission_fields: { 7: { scoreuuid1: '21' } },
+            };
+            expect(evaluateFormula(formula, data)).toBe(42);
+        });
+
+        test('returns null when form submission data is missing', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: scoreKey, fieldType: 'number' },
+                    { type: 'operator', value: '+' },
+                    { type: 'number', value: '1' },
+                ],
+            };
+            expect(evaluateFormula(formula, {})).toBeNull();
+        });
+    });
+});

package/src/__tests__/field-types/formula-fields.test.ts

@@ -0,0 +1,245 @@
+import {
+    CalculatedFormatForNumber,
+    FormFieldsByFormIdI,
+    FormInfo,
+    StructuredFormula,
+} from '../../interface/types';
+import {
+    buildFormFieldKey,
+    evaluateFormula,
+    formatCalculatedResult,
+    generateFillablePath,
+    parseExpression,
+    tokensToExpression,
+    validateFormula,
+} from '../../utils';
+
+/**
+ * Scenario tests for calculated (formula) fields.
+ *
+ * Formulas can reference three operand types — merge tags, fillable fields,
+ * form submission fields — and three numeric operations plus parentheses.
+ * These tests validate the full pipeline: parse expression -> structured
+ * formula -> validate -> evaluate at runtime -> format the result.
+ */
+
+const fillablePath = generateFillablePath('signer1', 'TipAmount');
+
+const forms: FormInfo[] = [{ id: 7, name: 'Inspection' }];
+const formFieldsByFormId: FormFieldsByFormIdI = {
+    7: [{ id: 'abc-123', header: 'Score', itemType: 'number' }],
+};
+const formScoreKey = buildFormFieldKey(7, 'abc-123');
+
+const validPaths = new Set(['Job.Total', 'Job.Discount', fillablePath, formScoreKey]);
+
+const baseNumberFormat: CalculatedFormatForNumber = {
+    resultType: 'number',
+    thousandsSeparator: true,
+    decimals: 2,
+    roundingMode: 'round',
+    decimalSeparatorEnabled: false,
+    decimalSeparator: '.',
+    prefixText: '$',
+    postfixText: '',
+};
+
+describe('formula (calculated) field scenarios', () => {
+    describe('with parsing an editor expression', () => {
+        const subject = (expression: string) =>
+            parseExpression(expression, validPaths, undefined, {
+                forms,
+                formFieldsByFormId,
+            });
+
+        test('produces structured tokens for a formula mixing merge tag and fillable', () => {
+            const tokens = subject('Job.Total - ' + fillablePath);
+            expect(tokens).toEqual([
+                { type: 'field', path: 'Job.Total', fieldType: 'number' },
+                { type: 'operator', value: '-' },
+                { type: 'field', path: fillablePath, fieldType: 'number' },
+            ]);
+        });
+
+        test('attaches form snapshot when token references a form submission field', () => {
+            const tokens = subject(formScoreKey);
+            expect(tokens).toHaveLength(1);
+            expect(tokens[0]).toEqual(
+                expect.objectContaining({
+                    type: 'field',
+                    path: formScoreKey,
+                    formSnapshot: expect.objectContaining({
+                        formId: 7,
+                        formName: 'Inspection',
+                        fieldName: 'Score',
+                    }),
+                }),
+            );
+        });
+
+        test('drops unknown field references silently', () => {
+            const tokens = subject('Job.Total + Unknown.Field');
+            expect(tokens.filter(t => t.type === 'field').map(t => t.type)).toEqual(['field']);
+        });
+
+        test('round-trips through tokensToExpression', () => {
+            const tokens = subject('( Job.Total - Job.Discount ) * 2');
+            const formula: StructuredFormula = { tokens };
+            expect(tokensToExpression(formula)).toBe('( Job.Total - Job.Discount ) * 2');
+        });
+    });
+
+    describe('with validation', () => {
+        test('accepts a balanced formula referencing known paths', () => {
+            const formula: StructuredFormula = {
+                tokens: parseExpression('Job.Total - Job.Discount', validPaths),
+            };
+            const result = validateFormula(formula, validPaths);
+            expect(result.valid).toBe(true);
+            expect(result.errors).toEqual([]);
+        });
+
+        test('rejects a formula with unbalanced parentheses', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'lparen' },
+                    { type: 'number', value: '1' },
+                ],
+            };
+            expect(validateFormula(formula, validPaths).errors).toContain(
+                'Unbalanced parentheses',
+            );
+        });
+
+        test('rejects a formula referencing an unknown field', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: 'Unknown.Field', fieldType: 'number' },
+                    { type: 'operator', value: '+' },
+                    { type: 'number', value: '1' },
+                ],
+            };
+            const result = validateFormula(formula, validPaths);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes('Unknown field'))).toBe(true);
+        });
+
+        test('rejects multiply/divide with date fields', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: 'd', fieldType: 'date' },
+                    { type: 'operator', value: '*' },
+                    { type: 'number', value: '2' },
+                ],
+            };
+            const result = validateFormula(formula, new Set(['d']), new Set(['d']));
+            expect(result.errors.some(e => e.includes('Multiply'))).toBe(true);
+        });
+    });
+
+    describe('with evaluation across operand sources', () => {
+        test('evaluates merge tag + fillable + form field operands together', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: 'Job.Total', fieldType: 'number' },
+                    { type: 'operator', value: '+' },
+                    { type: 'field', path: fillablePath, fieldType: 'number' },
+                    { type: 'operator', value: '+' },
+                    { type: 'field', path: formScoreKey, fieldType: 'number' },
+                ],
+            };
+            // formScoreKey resolves through __submission_fields.7.abc123 nested path
+            const data = {
+                Job: { Total: 100 },
+                [fillablePath]: '20',
+                __submission_fields: { 7: { abc123: '5' } },
+            };
+            expect(evaluateFormula(formula, data)).toBe(125);
+        });
+
+        test('honors parentheses and operator precedence', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'lparen' },
+                    { type: 'field', path: 'Job.Total', fieldType: 'number' },
+                    { type: 'operator', value: '-' },
+                    { type: 'field', path: 'Job.Discount', fieldType: 'number' },
+                    { type: 'rparen' },
+                    { type: 'operator', value: '*' },
+                    { type: 'number', value: '0.1' },
+                ],
+            };
+            expect(evaluateFormula(formula, { Job: { Total: 200, Discount: 50 } })).toBeCloseTo(
+                15,
+                5,
+            );
+        });
+
+        test('returns null when any field value is missing', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: 'Job.Total', fieldType: 'number' },
+                    { type: 'operator', value: '+' },
+                    { type: 'field', path: 'Job.Discount', fieldType: 'number' },
+                ],
+            };
+            expect(evaluateFormula(formula, { Job: { Total: 100 } })).toBeNull();
+        });
+
+        test('returns 0 when dividing by zero rather than throwing', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'number', value: '10' },
+                    { type: 'operator', value: '/' },
+                    { type: 'number', value: '0' },
+                ],
+            };
+            expect(evaluateFormula(formula, {})).toBe(0);
+        });
+    });
+
+    describe('with result formatting', () => {
+        test('applies currency prefix with thousands and decimals', () => {
+            const formatted = formatCalculatedResult(1234.5, {
+                ...baseNumberFormat,
+                resultType: 'currency',
+            });
+            expect(formatted).toBe('$1,234.50');
+        });
+
+        test('applies percent postfix when configured', () => {
+            const formatted = formatCalculatedResult(0.42, {
+                ...baseNumberFormat,
+                prefixText: '',
+                postfixText: '%',
+                decimals: 1,
+                thousandsSeparator: false,
+            });
+            expect(formatted).toBe('0.4%');
+        });
+
+        test('returns empty string for non-finite formula result', () => {
+            expect(formatCalculatedResult(NaN, baseNumberFormat)).toBe('');
+        });
+    });
+
+    describe('with full pipeline', () => {
+        test('parses, validates, evaluates, and formats a customer-discount formula', () => {
+            const expression = '( Job.Total - Job.Discount ) * 0.1';
+            const tokens = parseExpression(expression, validPaths);
+            const formula: StructuredFormula = { tokens };
+
+            const validation = validateFormula(formula, validPaths);
+            expect(validation.valid).toBe(true);
+
+            const value = evaluateFormula(formula, { Job: { Total: 1500, Discount: 200 } });
+            expect(value).toBe(130);
+
+            const formatted = formatCalculatedResult(value as number, {
+                ...baseNumberFormat,
+                resultType: 'currency',
+            });
+            expect(formatted).toBe('$130.00');
+        });
+    });
+});

package/src/__tests__/field-types/merge-tag-fields.test.ts

@@ -0,0 +1,208 @@
+import {
+    FieldTypeEnum,
+    SchemaObject,
+    StructuredFormula,
+} from '../../interface/types';
+import {
+    evaluateFormula,
+    extractGroupedFieldsFromDataModel,
+    getDataPointOptions,
+    getSchemaDataPointOptions,
+    resolvePdfDataValues,
+} from '../../utils';
+
+/**
+ * Scenario tests for merge tag (data model) fields.
+ *
+ * Merge tags come from a JSON schema describing the data model. They appear
+ * in the sidebar (grouped), in display-condition drop-downs (only fields
+ * flagged useInConditionals/useInCalculatedFields), and resolve to runtime
+ * values via dotted paths.
+ */
+
+const customerSchema: SchemaObject = {
+    type: 'object',
+    properties: {
+        FirstName: {
+            type: 'string',
+            title: 'First Name',
+            options: { useInConditionals: true },
+        },
+        LastName: { type: 'string', title: 'Last Name' },
+        Job: {
+            type: 'object',
+            title: 'Job',
+            properties: {
+                Total: {
+                    type: 'number',
+                    title: 'Total',
+                    options: { useInCalculatedFields: true, useInConditionals: true },
+                },
+                Discount: {
+                    type: 'number',
+                    title: 'Discount',
+                    options: { useInCalculatedFields: true },
+                },
+                Notes: { type: 'string', title: 'Notes' },
+                Technicians: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: { Name: { type: 'string' } },
+                    },
+                },
+            },
+        },
+    },
+};
+
+const customerData = {
+    FirstName: 'Jane',
+    LastName: 'Doe',
+    Job: {
+        Total: 150,
+        Discount: 20,
+        Notes: 'Standard service',
+        Price: { Amount: 100, Currency: 'USD' },
+        Custom: { Value: 'wrapped value' },
+    },
+};
+
+describe('merge tag (data model) field scenarios', () => {
+    describe('with sidebar field extraction', () => {
+        const subject = () => extractGroupedFieldsFromDataModel(customerSchema);
+
+        test('groups top-level simple fields under "Fields"', () => {
+            const groups = subject();
+            const fieldsGroup = groups.find(g => g.groupName === 'Fields');
+            expect(fieldsGroup?.fields.map(f => f.path)).toEqual(['FirstName', 'LastName']);
+        });
+
+        test('groups nested object fields under the object title', () => {
+            const groups = subject();
+            const jobGroup = groups.find(g => g.groupName === 'Job');
+            expect(jobGroup?.fields.map(f => f.path).sort()).toEqual([
+                'Job.Discount',
+                'Job.Notes',
+                'Job.Total',
+            ]);
+        });
+
+        test('excludes array properties', () => {
+            const groups = subject();
+            const jobGroup = groups.find(g => g.groupName === 'Job');
+            expect(jobGroup?.fields.some(f => f.path?.includes('Technicians'))).toBe(false);
+        });
+
+        test('marks numeric fields with fieldType number', () => {
+            const groups = subject();
+            const jobGroup = groups.find(g => g.groupName === 'Job');
+            const total = jobGroup?.fields.find(f => f.path === 'Job.Total');
+            expect(total?.fieldType).toBe('number');
+            expect(total?.type).toBe(FieldTypeEnum.dataModel);
+        });
+    });
+
+    describe('with calculated-only field extraction', () => {
+        test('returns only fields flagged useInCalculatedFields', () => {
+            const groups = extractGroupedFieldsFromDataModel(customerSchema, {
+                onlyUseInCalculatedFields: true,
+            });
+            const allPaths = groups.flatMap(g => g.fields.map(f => f.path)).sort();
+            expect(allPaths).toEqual(['Job.Discount', 'Job.Total']);
+        });
+    });
+
+    describe('with display-condition options', () => {
+        test('exposes fields flagged useInConditionals or useInCalculatedFields', () => {
+            const options = getSchemaDataPointOptions(customerSchema);
+            expect(options.map(o => o.fullKey).sort()).toEqual([
+                'FirstName',
+                'Job.Discount',
+                'Job.Total',
+            ]);
+        });
+
+        test('omits fields without either flag', () => {
+            const options = getSchemaDataPointOptions(customerSchema);
+            expect(options.some(o => o.fullKey === 'Job.Notes')).toBe(false);
+            expect(options.some(o => o.fullKey === 'LastName')).toBe(false);
+        });
+
+        test('uses dash-joined titles for nested fields', () => {
+            const options = getSchemaDataPointOptions(customerSchema);
+            const total = options.find(o => o.fullKey === 'Job.Total');
+            expect(total?.title).toBe('Job - Total');
+        });
+
+        test('combines schema and document field options sorted alphabetically', () => {
+            const fillableField = {
+                id: 'f1',
+                type: FieldTypeEnum.fillable,
+                subType: 'text' as const,
+                x: 0,
+                y: 0,
+                page: 1,
+                label: 'Custom Note',
+                width: 100,
+                height: 25,
+                path: 'fillable_signer1_CustomNote',
+            };
+            const options = getDataPointOptions(customerSchema, [fillableField]);
+            expect(options.map(o => o.title)).toEqual([
+                'Custom Note',
+                'First Name',
+                'Job - Discount',
+                'Job - Total',
+            ]);
+        });
+    });
+
+    describe('with value resolution at runtime', () => {
+        const subject = (path: string) => resolvePdfDataValues(customerData, path);
+
+        test('resolves a top-level string property', () => {
+            expect(subject('FirstName')).toBe('Jane');
+        });
+
+        test('resolves a nested numeric property as string', () => {
+            expect(subject('Job.Total')).toBe('150');
+        });
+
+        test('formats Amount/Currency objects as "{Currency} {Amount}"', () => {
+            expect(subject('Job.Price')).toBe('USD 100');
+        });
+
+        test('unwraps Value-wrapped objects', () => {
+            expect(subject('Job.Custom')).toBe('wrapped value');
+        });
+
+        test('returns empty string for missing path', () => {
+            expect(subject('Job.NonExistent')).toBe('');
+        });
+    });
+
+    describe('with merge tags used in a formula', () => {
+        test('evaluates Job.Total - Job.Discount using runtime data', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: 'Job.Total', fieldType: 'number' },
+                    { type: 'operator', value: '-' },
+                    { type: 'field', path: 'Job.Discount', fieldType: 'number' },
+                ],
+            };
+            expect(evaluateFormula(formula, customerData)).toBe(130);
+        });
+
+        test('returns null when merge tag value is missing', () => {
+            const formula: StructuredFormula = {
+                tokens: [
+                    { type: 'field', path: 'Job.NonExistent', fieldType: 'number' },
+                    { type: 'operator', value: '+' },
+                    { type: 'number', value: '10' },
+                ],
+            };
+            expect(evaluateFormula(formula, customerData)).toBeNull();
+        });
+    });
+});

package/src/components/field-config-panel/field-config-panel.tsx

@@ -162,6 +162,17 @@ export const FieldConfigPanel: FC<FieldConfigPanelProps> = ({
                     }
                 />
             )}
+            {field.type === FieldTypeEnum.fillable && field.subType === 'text' && (
+                <Checkbox
+                    label="Multi-line"
+                    checked={field.multiline ?? false}
+                    onChange={() =>
+                        onFieldConfigChange({
+                            multiline: !field.multiline,
+                        })
+                    }
+                />
+            )}
             {field.type === FieldTypeEnum.calculated && (
                 <FormulaGenerator
                     dataModel={dataModel}

package/src/components/pdf-fields-overlay/pdf-overlay-field-fillable.tsx

@@ -56,6 +56,16 @@ export const PdfOverlayFieldFillable: FC<PdfOverlayFieldFillableProps> = ({
             );
 
         default:
+            if (field.multiline) {
+                return (
+                    <textarea
+                        readOnly
+                        placeholder={placeholderText}
+                        className="dte-pdf-field-fillable"
+                        style={{ resize: 'none' }}
+                    />
+                );
+            }
             return (
                 <input
                     type="text"