@servicetitan/dte-pdf-editor 1.45.0 → 1.46.0

package/src/__tests__/field-types/display-condition-fields.test.ts

@@ -0,0 +1,340 @@
+import {
+    DataPointOption,
+    DisplayConditionState,
+    FieldTypeEnum,
+    FormFieldsByFormIdI,
+    PdfField,
+    SchemaObject,
+} from '../../interface/types';
+import {
+    buildFormFieldKey,
+    evaluateDisplayCondition,
+    generateFillablePath,
+    getDataPointOptions,
+    getDisplayConditionFieldTypeForKey,
+    getDocumentFieldsDataPointOptions,
+    getSchemaDataPointOptions,
+    inferDisplayConditionSourceKind,
+} from '../../utils';
+
+/**
+ * Scenario tests for display-condition fields.
+ *
+ * Display conditions can reference three sources:
+ *   - data model (merge tags)
+ *   - fillable fields (filled by recipient)
+ *   - form submission fields
+ *
+ * These tests cover source-kind inference, type resolution, and evaluation
+ * across each source with realistic AND/OR composition and show/hide behavior.
+ */
+
+const schema: SchemaObject = {
+    type: 'object',
+    properties: {
+        Customer: {
+            type: 'object',
+            title: 'Customer',
+            properties: {
+                Name: {
+                    type: 'string',
+                    title: 'Name',
+                    options: { useInConditionals: true },
+                },
+                Age: {
+                    type: 'number',
+                    title: 'Age',
+                    options: { useInConditionals: true },
+                },
+            },
+        },
+    },
+};
+
+const fillableField: PdfField = {
+    id: 'fillable-1',
+    type: FieldTypeEnum.fillable,
+    subType: 'text',
+    x: 0,
+    y: 0,
+    page: 1,
+    label: 'Email',
+    width: 100,
+    height: 25,
+    recipient: 'signer1',
+    path: generateFillablePath('signer1', 'Email'),
+};
+
+const formFieldsByFormId: FormFieldsByFormIdI = {
+    7: [
+        { id: 'abc-123', header: 'Score', itemType: 'number' },
+        { id: 'def-456', header: 'Comment', itemType: 'text' },
+    ],
+};
+
+const formScoreKey = buildFormFieldKey(7, 'abc-123');
+const formCommentKey = buildFormFieldKey(7, 'def-456');
+
+describe('display-condition field scenarios', () => {
+    describe('with source-kind inference', () => {
+        const mergeTagOptions: DataPointOption[] = getSchemaDataPointOptions(schema);
+        const fillableOptions: DataPointOption[] = getDocumentFieldsDataPointOptions([
+            fillableField,
+        ]);
+        const subject = (key: string) =>
+            inferDisplayConditionSourceKind(key, mergeTagOptions, fillableOptions);
+
+        test.each([
+            ['data model', 'Customer.Name', FieldTypeEnum.dataModel],
+            ['fillable', fillableField.path!, FieldTypeEnum.fillable],
+            ['form', formScoreKey, FieldTypeEnum.forms],
+        ])('infers %s source from key', (_, key, expected) => {
+            expect(subject(key)).toBe(expected);
+        });
+
+        test('returns null when key is empty', () => {
+            expect(subject('')).toBeNull();
+        });
+
+        test('returns null for unknown key', () => {
+            expect(subject('unknown.path')).toBeNull();
+        });
+    });
+
+    describe('with field-type resolution', () => {
+        const mergeTagOptions = getSchemaDataPointOptions(schema);
+        const fillableOptions = getDocumentFieldsDataPointOptions([fillableField]);
+
+        test('returns number for numeric merge tag', () => {
+            expect(
+                getDisplayConditionFieldTypeForKey(
+                    'Customer.Age',
+                    mergeTagOptions,
+                    fillableOptions,
+                    formFieldsByFormId,
+                ),
+            ).toBe('number');
+        });
+
+        test('returns string for fillable text field', () => {
+            expect(
+                getDisplayConditionFieldTypeForKey(
+                    fillableField.path!,
+                    mergeTagOptions,
+                    fillableOptions,
+                    formFieldsByFormId,
+                ),
+            ).toBe('string');
+        });
+
+        test('returns number for numeric form field', () => {
+            expect(
+                getDisplayConditionFieldTypeForKey(
+                    formScoreKey,
+                    mergeTagOptions,
+                    fillableOptions,
+                    formFieldsByFormId,
+                ),
+            ).toBe('number');
+        });
+
+        test('returns string for text form field', () => {
+            expect(
+                getDisplayConditionFieldTypeForKey(
+                    formCommentKey,
+                    mergeTagOptions,
+                    fillableOptions,
+                    formFieldsByFormId,
+                ),
+            ).toBe('string');
+        });
+    });
+
+    describe('with options exposed to the condition picker', () => {
+        test('includes merge tag and fillable options sorted by title', () => {
+            const options = getDataPointOptions(schema, [fillableField]);
+            expect(options.map(o => o.title)).toEqual([
+                'Customer - Age',
+                'Customer - Name',
+                'Email',
+            ]);
+        });
+    });
+
+    describe('with condition evaluation on merge tag source', () => {
+        const subject = (state: DisplayConditionState, data: Record<string, unknown>) =>
+            evaluateDisplayCondition(state, data);
+
+        const state: DisplayConditionState = {
+            behavior: 'show',
+            groups: [
+                {
+                    id: 'g',
+                    conditions: [
+                        {
+                            id: 'c',
+                            dataPointKey: 'Customer.Age',
+                            operator: 'num_gte',
+                            value: '18',
+                        },
+                    ],
+                },
+            ],
+        };
+
+        test('shows field when numeric merge tag is greater than threshold', () => {
+            expect(subject(state, { Customer: { Age: 25 } })).toBe(true);
+        });
+
+        test('hides field when numeric merge tag is below threshold', () => {
+            expect(subject(state, { Customer: { Age: 10 } })).toBe(false);
+        });
+    });
+
+    describe('with condition evaluation on fillable source', () => {
+        const subject = (state: DisplayConditionState, data: Record<string, unknown>) =>
+            evaluateDisplayCondition(state, data);
+
+        test('matches fillable value via its fillable_recipient_name path', () => {
+            const state: DisplayConditionState = {
+                behavior: 'show',
+                groups: [
+                    {
+                        id: 'g',
+                        conditions: [
+                            {
+                                id: 'c',
+                                dataPointKey: fillableField.path!,
+                                operator: 'contains',
+                                value: '@example.com',
+                            },
+                        ],
+                    },
+                ],
+            };
+            expect(subject(state, { [fillableField.path!]: 'jane@example.com' })).toBe(true);
+            expect(subject(state, { [fillableField.path!]: 'jane@other.com' })).toBe(false);
+        });
+    });
+
+    describe('with condition evaluation on form-field source', () => {
+        const subject = (state: DisplayConditionState, data: Record<string, unknown>) =>
+            evaluateDisplayCondition(state, data);
+
+        test('reads numeric form field via its __submission_fields path', () => {
+            const state: DisplayConditionState = {
+                behavior: 'show',
+                groups: [
+                    {
+                        id: 'g',
+                        conditions: [
+                            {
+                                id: 'c',
+                                dataPointKey: formScoreKey,
+                                operator: 'num_gt',
+                                value: '50',
+                            },
+                        ],
+                    },
+                ],
+            };
+
+            // Form values land at __submission_fields.{formId}.{fieldId}
+            const data = {
+                __submission_fields: { 7: { abc123: 75 } },
+            };
+            expect(subject(state, data)).toBe(true);
+        });
+    });
+
+    describe('with AND/OR composition across sources', () => {
+        const subject = (state: DisplayConditionState, data: Record<string, unknown>) =>
+            evaluateDisplayCondition(state, data);
+
+        const state: DisplayConditionState = {
+            behavior: 'show',
+            groups: [
+                {
+                    id: 'g1',
+                    conditions: [
+                        {
+                            id: 'c1',
+                            dataPointKey: 'Customer.Age',
+                            operator: 'num_gte',
+                            value: '18',
+                        },
+                        {
+                            id: 'c2',
+                            logicalOperator: 'and',
+                            dataPointKey: fillableField.path!,
+                            operator: 'is_not_empty',
+                            value: '',
+                        },
+                    ],
+                },
+                {
+                    id: 'g2',
+                    logicalOperator: 'or',
+                    conditions: [
+                        {
+                            id: 'c3',
+                            dataPointKey: formScoreKey,
+                            operator: 'num_gte',
+                            value: '90',
+                        },
+                    ],
+                },
+            ],
+        };
+
+        test('matches when first AND group is satisfied', () => {
+            const data = {
+                Customer: { Age: 25 },
+                [fillableField.path!]: 'jane@example.com',
+                __submission_fields: { 7: { abc123: 0 } },
+            };
+            expect(subject(state, data)).toBe(true);
+        });
+
+        test('matches when second OR group is satisfied', () => {
+            const data = {
+                Customer: { Age: 10 },
+                [fillableField.path!]: '',
+                __submission_fields: { 7: { abc123: 95 } },
+            };
+            expect(subject(state, data)).toBe(true);
+        });
+
+        test('hides when neither group is satisfied', () => {
+            const data = {
+                Customer: { Age: 10 },
+                [fillableField.path!]: '',
+                __submission_fields: { 7: { abc123: 50 } },
+            };
+            expect(subject(state, data)).toBe(false);
+        });
+    });
+
+    describe('with hide behavior', () => {
+        test('inverts result to hide when condition matches', () => {
+            const state: DisplayConditionState = {
+                behavior: 'hide',
+                groups: [
+                    {
+                        id: 'g',
+                        conditions: [
+                            {
+                                id: 'c',
+                                dataPointKey: 'Customer.Name',
+                                operator: 'is_equal_to',
+                                value: 'Internal',
+                            },
+                        ],
+                    },
+                ],
+            };
+            expect(evaluateDisplayCondition(state, { Customer: { Name: 'Internal' } })).toBe(false);
+            expect(evaluateDisplayCondition(state, { Customer: { Name: 'External' } })).toBe(true);
+        });
+    });
+});

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