@servicetitan/dte-pdf-editor 1.45.0 → 1.47.0

package/src/__tests__/field-types/e-sign-fields.test.ts

@@ -0,0 +1,97 @@
+import {
+    ESignFieldType,
+    FieldTypeEnum,
+    PdfField,
+    RecipientInfo,
+} from '../../interface/types';
+import {
+    generateESignPath,
+    getDocumentFieldsDataPointOptions,
+    getFieldBackgroundColor,
+    getFieldPlaceholderText,
+    mapColorsToRecipients,
+} from '../../utils';
+
+/**
+ * Scenario tests for e-sign fields.
+ *
+ * E-sign fields belong to a recipient and use one of four subtypes:
+ * signature, initials, dateSigned, fullName. They are excluded from the
+ * display-condition source list since their values are not user-typed data.
+ */
+
+const buildESignField = (overrides: Partial<PdfField> = {}): PdfField => ({
+    id: 'esign-1',
+    type: FieldTypeEnum.eSign,
+    subType: ESignFieldType.signature,
+    x: 0,
+    y: 0,
+    page: 1,
+    label: 'Signature',
+    width: 200,
+    height: 50,
+    recipient: 'signer1',
+    path: generateESignPath('signer1', ESignFieldType.signature),
+    ...overrides,
+});
+
+describe('e-sign field scenarios', () => {
+    describe('with path generation per subtype', () => {
+        test.each([
+            [ESignFieldType.signature, 'esign_signer1_signature'],
+            [ESignFieldType.initials, 'esign_signer1_initials'],
+            [ESignFieldType.dateSigned, 'esign_signer1_dateSigned'],
+            [ESignFieldType.fullName, 'esign_signer1_fullName'],
+        ])('generates "%s" path for sub-type', (subType, expected) => {
+            expect(generateESignPath('signer1', subType)).toBe(expected);
+        });
+
+        test('keeps recipient and subtype distinct in the path', () => {
+            expect(generateESignPath('signer2', ESignFieldType.initials)).toBe(
+                'esign_signer2_initials',
+            );
+        });
+    });
+
+    describe('with recipient color resolution', () => {
+        const recipients: RecipientInfo[] = [
+            { id: 1, name: 'signer1', displayName: 'Signer 1' },
+            { id: 2, name: 'signer2', displayName: 'Signer 2' },
+        ];
+        const colors = mapColorsToRecipients(recipients);
+
+        test('assigns a background color for each recipient', () => {
+            const field = buildESignField({ recipient: 'signer1' });
+            expect(getFieldBackgroundColor(field.recipient, colors)).toBeDefined();
+        });
+
+        test('returns "none" for an unknown recipient', () => {
+            expect(getFieldBackgroundColor('unknown', colors)).toBe('none');
+        });
+    });
+
+    describe('with placeholder text', () => {
+        test('uses subtype-friendly label without required marker', () => {
+            const field = buildESignField({ label: 'Signature' });
+            expect(getFieldPlaceholderText(field)).toBe('Signature');
+        });
+
+        test('adds required marker when field is required', () => {
+            const field = buildESignField({ label: 'Initials', required: true });
+            expect(getFieldPlaceholderText(field)).toBe('Initials *');
+        });
+    });
+
+    describe('with display-condition options', () => {
+        test('excludes e-sign fields from document field options', () => {
+            const fields: PdfField[] = [
+                buildESignField({ id: '1', subType: ESignFieldType.signature }),
+                buildESignField({ id: '2', subType: ESignFieldType.initials }),
+                buildESignField({ id: '3', subType: ESignFieldType.dateSigned }),
+                buildESignField({ id: '4', subType: ESignFieldType.fullName }),
+            ];
+
+            expect(getDocumentFieldsDataPointOptions(fields)).toEqual([]);
+        });
+    });
+});

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

@@ -0,0 +1,180 @@
+import { FieldTypeEnum, PdfField, RecipientInfo } from '../../interface/types';
+import {
+    generateFillablePath,
+    getDocumentFieldsDataPointOptions,
+    getFieldBackgroundColor,
+    getFieldPlaceholderText,
+    mapColorsToRecipients,
+    parseFillablePathName,
+} from '../../utils';
+
+/**
+ * Scenario tests for fillable fields.
+ *
+ * Fillable fields support five sub-types: text, number, date, checkbox, radio.
+ * These tests validate the full flow: path generation -> parsing -> placeholder
+ * -> color resolution -> data-point option export for downstream conditions.
+ */
+
+const buildFillableField = (overrides: Partial<PdfField> = {}): PdfField => ({
+    id: 'field-1',
+    type: FieldTypeEnum.fillable,
+    subType: 'text',
+    x: 0,
+    y: 0,
+    page: 1,
+    label: 'Customer Name',
+    width: 200,
+    height: 25,
+    recipient: 'signer1',
+    path: generateFillablePath('signer1', 'CustomerName'),
+    ...overrides,
+});
+
+const recipients: RecipientInfo[] = [
+    { id: 1, name: 'signer1', displayName: 'Signer 1' },
+    { id: 2, name: 'signer2', displayName: 'Signer 2' },
+];
+
+describe('fillable field scenarios', () => {
+    describe('with text sub-type', () => {
+        const field = buildFillableField();
+
+        test('generates path with recipient and field name', () => {
+            expect(field.path).toBe('fillable_signer1_CustomerName');
+        });
+
+        test('parses original name back from path', () => {
+            expect(parseFillablePathName(field.path)).toBe('CustomerName');
+        });
+
+        test('builds placeholder text from label', () => {
+            expect(getFieldPlaceholderText(field)).toBe('Customer Name');
+        });
+
+        test('marks placeholder as required when required is true', () => {
+            expect(getFieldPlaceholderText({ ...field, required: true })).toBe(
+                'Customer Name *',
+            );
+        });
+
+        test('exports as string data point option', () => {
+            const options = getDocumentFieldsDataPointOptions([field]);
+            expect(options).toEqual([
+                {
+                    fieldType: 'string',
+                    fullKey: 'fillable_signer1_CustomerName',
+                    title: 'Customer Name',
+                },
+            ]);
+        });
+    });
+
+    describe('with number sub-type', () => {
+        const field = buildFillableField({
+            subType: 'number',
+            label: 'Amount',
+            path: generateFillablePath('signer1', 'Amount'),
+        });
+
+        test('exports as number data point option', () => {
+            const options = getDocumentFieldsDataPointOptions([field]);
+            expect(options[0].fieldType).toBe('number');
+        });
+
+        test('keeps path format consistent with other sub-types', () => {
+            expect(field.path).toBe('fillable_signer1_Amount');
+        });
+    });
+
+    describe('with date sub-type', () => {
+        const field = buildFillableField({
+            subType: 'date',
+            label: 'Effective Date',
+            path: generateFillablePath('signer1', 'EffectiveDate'),
+        });
+
+        test('exports as string data point (dates are evaluated by string comparison)', () => {
+            const options = getDocumentFieldsDataPointOptions([field]);
+            expect(options[0].fieldType).toBe('string');
+        });
+
+        test('preserves field metadata when extracted as option', () => {
+            const options = getDocumentFieldsDataPointOptions([field]);
+            expect(options[0].title).toBe('Effective Date');
+            expect(options[0].fullKey).toBe('fillable_signer1_EffectiveDate');
+        });
+    });
+
+    describe('with checkbox sub-type', () => {
+        const field = buildFillableField({
+            subType: 'checkbox',
+            label: 'Agree to terms',
+            path: generateFillablePath('signer1', 'AgreeToTerms'),
+        });
+
+        test('exports as string data point', () => {
+            const options = getDocumentFieldsDataPointOptions([field]);
+            expect(options[0].fieldType).toBe('string');
+        });
+    });
+
+    describe('with radio sub-type', () => {
+        const field = buildFillableField({
+            subType: 'radio',
+            label: 'Yes',
+            path: generateFillablePath('signer1', 'Choice'),
+        });
+
+        test('exports as string data point', () => {
+            const options = getDocumentFieldsDataPointOptions([field]);
+            expect(options[0].fieldType).toBe('string');
+        });
+    });
+
+    describe('with multi-recipient color resolution', () => {
+        const colors = mapColorsToRecipients(recipients);
+        const signer1Field = buildFillableField({ recipient: 'signer1' });
+        const signer2Field = buildFillableField({ id: 'f2', recipient: 'signer2' });
+
+        test('returns distinct background colors per recipient', () => {
+            expect(getFieldBackgroundColor(signer1Field.recipient, colors)).not.toBe(
+                getFieldBackgroundColor(signer2Field.recipient, colors),
+            );
+        });
+
+        test('returns "none" when field has no recipient', () => {
+            expect(getFieldBackgroundColor(undefined, colors)).toBe('none');
+        });
+    });
+
+    describe('with mixed field list', () => {
+        const fields: PdfField[] = [
+            buildFillableField({
+                id: 'a',
+                label: 'Z Last',
+                path: generateFillablePath('signer1', 'ZLast'),
+            }),
+            buildFillableField({
+                id: 'b',
+                label: 'A First',
+                path: generateFillablePath('signer1', 'AFirst'),
+            }),
+            buildFillableField({
+                id: 'c',
+                label: 'No Path',
+                path: undefined,
+            }),
+            {
+                ...buildFillableField({ id: 'd', label: 'Sig' }),
+                type: FieldTypeEnum.eSign,
+                path: 'esign_signer1_signature',
+            },
+        ];
+
+        test('returns only fillable fields with a path, sorted by title', () => {
+            const options = getDocumentFieldsDataPointOptions(fields);
+            expect(options.map(o => o.title)).toEqual(['A First', 'Z Last']);
+        });
+    });
+});

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