@servicetitan/dte-pdf-editor 1.45.0 → 1.47.0

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-fields-overlay.tsx

@@ -1,4 +1,4 @@
-import { FC, MouseEvent, RefObject } from 'react';
+import { FC, MouseEvent, RefObject, useMemo } from 'react';
 import { PdfField } from '../../interface/types';
 import { PdfOverlayField } from './pdf-overlay-field';
 
@@ -27,6 +27,16 @@ export const PdfFieldsOverlay: FC<PdfFieldsOverlayProps> = ({
     recipientsColors,
     selectedField,
 }) => {
+    const pathToLabel = useMemo(() => {
+        const map = new Map<string, string>();
+        for (const f of fields) {
+            if (f.path && f.label) {
+                map.set(f.path, f.label);
+            }
+        }
+        return map;
+    }, [fields]);
+
     return (
         <div className="dte-pdf-field-overlay skeleton-item">
             {fields.map(field => (
@@ -43,6 +53,7 @@ export const PdfFieldsOverlay: FC<PdfFieldsOverlayProps> = ({
                     isSelected={selectedField?.id === field.id}
                     recipientsColors={recipientsColors}
                     isSameGroup={selectedField?.path === field.path}
+                    pathToLabel={pathToLabel}
                 />
             ))}
         </div>

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

@@ -1,14 +1,30 @@
-import { FC } from 'react';
+import { FC, useMemo } from 'react';
 import { PdfField } from '../../interface/types';
+import { formulaToDisplayText } from '../../utils';
 
 interface PdfOverlayFieldCalculatedProps {
     field: PdfField;
+    pathToLabel?: Map<string, string>;
 }
 
-export const PdfOverlayFieldCalculated: FC<PdfOverlayFieldCalculatedProps> = ({ field }) => {
+export const PdfOverlayFieldCalculated: FC<PdfOverlayFieldCalculatedProps> = ({
+    field,
+    pathToLabel,
+}) => {
+    const displayText = useMemo(() => {
+        const formulaText = formulaToDisplayText(field.formula, pathToLabel);
+        if (formulaText) {
+            return formulaText;
+        }
+        if (field.label) {
+            return field.label;
+        }
+        return field.path;
+    }, [field.formula, field.label, field.path, pathToLabel]);
+
     return (
-        <span>
-            {field.label ? field.label : field.path}
+        <span className="ellipsis" title={displayText}>
+            {displayText}
             {field.required ? '*' : ''}
         </span>
     );

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"

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

@@ -17,6 +17,7 @@ interface PdfOverlayFieldProps {
     isSameGroup: boolean;
     recipientsColors: Record<string, string>;
     pdfWrapperRef: RefObject<HTMLDivElement>;
+    pathToLabel?: Map<string, string>;
     onFieldConfigChange(updates: Partial<PdfField>): void;
     handleAddNewField(field: PdfField): void;
     onFieldClick(fieldId: string, e: MouseEvent): void;
@@ -34,6 +35,7 @@ export const PdfOverlayField: FC<PdfOverlayFieldProps> = ({
     onFieldConfigChange,
     onFieldMove,
     onFieldResize,
+    pathToLabel,
     pdfWrapperRef,
     recipientsColors,
 }) => {
@@ -75,7 +77,9 @@ export const PdfOverlayField: FC<PdfOverlayFieldProps> = ({
             className={`dte-pdf-field ${isSelected ? '--selected' : '--unselected'} ${isDragging ? '--dragging' : ''} ${isSameGroup ? '--colored' : ''} ${error ? '--error' : ''}`}
             style={style}
         >
-            {field.type === FieldTypeEnum.calculated && <PdfOverlayFieldCalculated field={field} />}
+            {field.type === FieldTypeEnum.calculated && (
+                <PdfOverlayFieldCalculated field={field} pathToLabel={pathToLabel} />
+            )}
             {field.type === FieldTypeEnum.eSign && <PdfOverlayFieldESign field={field} />}
             {(field.type === FieldTypeEnum.dataModel || field.type === FieldTypeEnum.forms) && (
                 <PdfOverlayFieldDataModel field={field} />

package/src/components/pdf-view/pdf-view-calculated.tsx

@@ -1,14 +1,20 @@
 import { FC, useMemo } from 'react';
-import { DataModelValues, PdfField } from '../../interface/types';
+import { DataModelValues, PdfField, PdfViewMode } from '../../interface/types';
 import { evaluateFormula, formatCalculatedResult, resolvePdfDataValues } from '../../utils';
 
 interface PdfViewCalculatedProps {
     field: PdfField;
     data?: DataModelValues;
     holidays?: string[];
+    viewMode?: PdfViewMode;
 }
 
-export const PdfViewCalculated: FC<PdfViewCalculatedProps> = ({ data, field, holidays }) => {
+export const PdfViewCalculated: FC<PdfViewCalculatedProps> = ({
+    data,
+    field,
+    holidays,
+    viewMode,
+}) => {
     const displayValue = useMemo(() => {
         if (field.formula?.tokens?.length) {
             const value = evaluateFormula(field.formula, data, holidays);
@@ -23,5 +29,9 @@ export const PdfViewCalculated: FC<PdfViewCalculatedProps> = ({ data, field, hol
         return field.label ?? '';
     }, [data, field.formula, field.formulaFormat, field.label, field.path, holidays]);
 
-    return <div className="dte-pdf-field-value">{displayValue}</div>;
+    const isPreview = viewMode === 'preview';
+    const shouldShowPreviewFallback = isPreview && displayValue === '';
+    const content = shouldShowPreviewFallback ? field.label || 'Calculated Field' : displayValue;
+
+    return <div className="dte-pdf-field-value">{content}</div>;
 };