@servicetitan/dte-pdf-editor 1.92.4 → 1.93.0

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

@@ -2,16 +2,21 @@ import { FieldTypeEnum, type PdfField, type RecipientInfo } from '../../interfac
 import {
     generateFillablePath,
     getDocumentFieldsDataPointOptions,
-    getFieldBackgroundColor,
+    getDropdownFieldItems,
+    getFieldColor,
     getFieldPlaceholderText,
+    getFillableEffectiveValue,
+    getTodayDateInputValue,
+    isRadioDefaultSelected,
+    isRadioOptionChecked,
     mapColorsToRecipients,
-    parseFillablePathName,
+    parseFillablePathName
 } from '../../utils';
 
 /**
  * Scenario tests for fillable fields.
  *
- * Fillable fields support five sub-types: text, number, date, checkbox, radio.
+ * Fillable fields support six sub-types: text, number, date, checkbox, radio, dropdown.
  * These tests validate the full flow: path generation -> parsing -> placeholder
  * -> color resolution -> data-point option export for downstream conditions.
  */
@@ -149,19 +154,150 @@ describe('fillable field scenarios', () => {
         });
     });
 
+    describe('with default value (DTE-4668)', () => {
+        test('a field with a configured default shows it when nothing has been filled yet', () => {
+            const field = buildFillableField({ default: { type: 'text', value: 'Acme Inc.' } });
+            expect(getFillableEffectiveValue(field, undefined)).toBe('Acme Inc.');
+        });
+
+        test('a field with no default round-trips without one and still starts blank', () => {
+            const field = buildFillableField();
+            expect(field.default).toBeUndefined();
+            expect(getFillableEffectiveValue(field, undefined)).toBeUndefined();
+        });
+
+        test('an explicit filled-in value always overrides the default', () => {
+            const field = buildFillableField({ default: { type: 'text', value: 'Acme Inc.' } });
+            expect(getFillableEffectiveValue(field, 'Contoso Ltd.')).toBe('Contoso Ltd.');
+        });
+
+        test('an explicit blank is a stored answer and is not re-defaulted on reload', () => {
+            const field = buildFillableField({
+                subType: 'checkbox',
+                default: { type: 'checkbox', value: true },
+            });
+            // The recipient unchecked it - `false` is present, not a missing path.
+            expect(getFillableEffectiveValue(field, false)).toBe(false);
+        });
+
+        test('a date field can default to a fixed calendar date', () => {
+            const field = buildFillableField({
+                subType: 'date',
+                default: { type: 'date', value: '2026-01-01' },
+            });
+            expect(getFillableEffectiveValue(field, undefined)).toBe('2026-01-01');
+        });
+
+        test('a date field can default to today, resolved at render time rather than frozen at authoring time', () => {
+            const field = buildFillableField({ subType: 'date', default: { type: 'today' } });
+            expect(getFillableEffectiveValue(field, undefined)).toBe(getTodayDateInputValue());
+        });
+
+        test('a radio option default only flags that specific option, not a scalar on the group', () => {
+            const path = generateFillablePath('signer1', 'Choice');
+            const defaultOption = buildFillableField({
+                id: 'opt-yes',
+                subType: 'radio',
+                path,
+                default: { type: 'radio' },
+            });
+            const otherOption = buildFillableField({ id: 'opt-no', subType: 'radio', path });
+
+            expect(isRadioDefaultSelected(defaultOption)).toBe(true);
+            expect(isRadioDefaultSelected(otherOption)).toBe(false);
+            // Nothing chosen yet for the group's own path -> the flagged option reads as checked.
+            expect(isRadioOptionChecked(defaultOption, undefined)).toBe(true);
+            expect(isRadioOptionChecked(otherOption, undefined)).toBe(false);
+        });
+
+        test('a chosen radio option in the same group overrides the default flag on reload', () => {
+            const path = generateFillablePath('signer1', 'Choice');
+            const defaultOption = buildFillableField({
+                id: 'opt-yes',
+                subType: 'radio',
+                path,
+                default: { type: 'radio' },
+            });
+            const otherOption = buildFillableField({ id: 'opt-no', subType: 'radio', path });
+
+            // The recipient picked "opt-no" - that id is now the group's stored value at `path`.
+            expect(isRadioOptionChecked(defaultOption, 'opt-no')).toBe(false);
+            expect(isRadioOptionChecked(otherOption, 'opt-no')).toBe(true);
+        });
+    });
+
+    describe('with dropdown sub-type', () => {
+        const field = buildFillableField({
+            subType: 'dropdown',
+            label: 'Preferred Contact',
+            path: generateFillablePath('signer1', 'PreferredContact'),
+            dropdownItems: [
+                { value: 'email', label: 'Email' },
+                { value: 'phone', label: 'Phone' },
+            ],
+        });
+
+        test('exports as string data point option', () => {
+            const options = getDocumentFieldsDataPointOptions([field]);
+            expect(options[0].fieldType).toBe('string');
+        });
+
+        test('reads back the configured items', () => {
+            expect(getDropdownFieldItems(field)).toEqual([
+                { value: 'email', label: 'Email' },
+                { value: 'phone', label: 'Phone' },
+            ]);
+        });
+
+        test('returns an empty list when items are missing (pre-existing documents)', () => {
+            expect(getDropdownFieldItems({ ...field, dropdownItems: undefined })).toEqual([]);
+        });
+
+        test('returns an empty list when items are malformed', () => {
+            expect(
+                getDropdownFieldItems({ ...field, dropdownItems: 'not-an-array' as any }),
+            ).toEqual([]);
+            expect(
+                getDropdownFieldItems({
+                    ...field,
+                    dropdownItems: [{ value: 'email' }] as any,
+                }),
+            ).toEqual([]);
+        });
+
+        describe('with a default item (FE-only `dropdown` variant, no backend equivalent)', () => {
+            const fieldWithDefault = buildFillableField({
+                ...field,
+                default: { type: 'dropdown', value: 'phone' },
+            });
+
+            test('shows the defaulted item value when nothing has been filled yet', () => {
+                expect(getFillableEffectiveValue(fieldWithDefault, undefined)).toBe('phone');
+            });
+
+            test('an explicit stored value overrides the default', () => {
+                expect(getFillableEffectiveValue(fieldWithDefault, 'email')).toBe('email');
+            });
+
+            test('starts blank when no item is flagged as default', () => {
+                expect(getFillableEffectiveValue(field, undefined)).toBeUndefined();
+            });
+        });
+    });
+
     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),
+            expect(getFieldColor(signer1Field.recipient, colors)).not.toBe(
+                getFieldColor(signer2Field.recipient, colors),
             );
         });
 
         test('returns "none" when field has no recipient', () => {
-            expect(getFieldBackgroundColor(undefined, colors)).toBe('none');
+            expect(getFieldColor(undefined, colors)).toBe('none');
         });
     });
 

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

@@ -0,0 +1,138 @@
+import { Button, Flex, SelectFieldSync, Text, TextField } from '@servicetitan/anvil2';
+import AddCircleIcon from '@servicetitan/anvil2/assets/icons/material/round/add_circle.svg';
+import DeleteIcon from '@servicetitan/anvil2/assets/icons/material/round/delete.svg';
+import { FC } from 'react';
+import { DROPDOWN_FIELD_MAX_ITEMS } from '../../constants';
+import { type FillableDropdownItem, type PdfField } from '../../interface/types';
+import { getDropdownFieldItems } from '../../utils';
+
+interface DropdownFieldItemsProps {
+    field: PdfField;
+    onFieldConfigChange(updates: Partial<PdfField>): void;
+}
+
+export const DropdownFieldItems: FC<DropdownFieldItemsProps> = ({ field, onFieldConfigChange }) => {
+    const items = getDropdownFieldItems(field);
+    const defaultValue = field.default?.type === 'dropdown' ? field.default.value : undefined;
+
+    const setItems = (nextItems: FillableDropdownItem[]) => {
+        onFieldConfigChange({ dropdownItems: nextItems });
+    };
+
+    const handleAddItem = () => {
+        setItems([...items, { value: '', label: '' }]);
+    };
+
+    const handleRemoveItem = (index: number) => {
+        const nextItems = items.filter((_, i) => i !== index);
+        onFieldConfigChange({
+            dropdownItems: nextItems,
+            ...(items[index].value === defaultValue ? { default: undefined } : {}),
+        });
+    };
+
+    const handleUpdateItem = (index: number, updates: Partial<FillableDropdownItem>) => {
+        const isDefaultItem = items[index].value === defaultValue;
+        const nextItems = items.map((item, i) => (i === index ? { ...item, ...updates } : item));
+        onFieldConfigChange({
+            dropdownItems: nextItems,
+            ...(isDefaultItem
+                ? { default: { type: 'dropdown', value: nextItems[index].value } }
+                : {}),
+        });
+    };
+
+    const getDuplicateFlags = (values: string[]): boolean[] => {
+        const counts = new Map<string, number>();
+        values.forEach(value => {
+            if (value) {
+                counts.set(value, (counts.get(value) ?? 0) + 1);
+            }
+        });
+        return values.map(value => !!value && (counts.get(value) ?? 0) > 1);
+    };
+
+    const isDuplicateValue = getDuplicateFlags(items.map(item => item.value));
+    const isDuplicateLabel = getDuplicateFlags(items.map(item => item.label));
+
+    const itemOptions = items.map((item, index) => ({
+        id: index,
+        label: item.label || item.value || `Item ${index + 1}`,
+    }));
+    const selectedDefaultIndex = items.findIndex(item => item.value === defaultValue);
+    const selectedDefaultOption =
+        selectedDefaultIndex === -1 ? null : itemOptions[selectedDefaultIndex];
+
+    const handleDefaultChange = (option: { id: number; label: string } | null) => {
+        const selectedItem = option ? items[option.id] : undefined;
+        onFieldConfigChange({
+            default: selectedItem ? { type: 'dropdown', value: selectedItem.value } : undefined,
+        });
+    };
+
+    return (
+        <Flex direction="column" gap="2">
+            <Flex justifyContent="space-between" alignItems="center">
+                <Text variant="body" size="small">
+                    Items
+                </Text>
+                <Button
+                    size="small"
+                    appearance="ghost"
+                    icon={{ before: AddCircleIcon }}
+                    disabled={items.length >= DROPDOWN_FIELD_MAX_ITEMS}
+                    onClick={handleAddItem}
+                >
+                    Add Item
+                </Button>
+            </Flex>
+
+            {items.map((item, index) => (
+                /*
+                 * items are plain {value, label} pairs with no separate id, and value/label are
+                 * exactly what's being edited and validated for uniqueness here, so neither is a
+                 * safe list key.
+                 */
+                // eslint-disable-next-line react/no-array-index-key
+                <Flex key={index} direction="row" gap="1" className="dte-rule-card">
+                    <TextField
+                        size="small"
+                        aria-label="Item value"
+                        placeholder="Value"
+                        error={(isDuplicateValue[index] && 'Must be unique') || !item.value}
+                        value={item.value}
+                        style={{ flex: 1, minWidth: 0 }}
+                        onChange={e => handleUpdateItem(index, { value: e.target.value })}
+                    />
+                    <TextField
+                        size="small"
+                        aria-label="Item label"
+                        placeholder="Label"
+                        error={(isDuplicateLabel[index] && 'Must be unique') || !item.label}
+                        value={item.label}
+                        style={{ flex: 1, minWidth: 0 }}
+                        onChange={e => handleUpdateItem(index, { label: e.target.value })}
+                    />
+                    <Flex justifyContent="flex-end" gap="1">
+                        <Button
+                            size="small"
+                            disabled={items.length <= 1}
+                            appearance="secondary"
+                            aria-label="Remove item"
+                            icon={{ before: DeleteIcon }}
+                            onClick={() => handleRemoveItem(index)}
+                        />
+                    </Flex>
+                </Flex>
+            ))}
+
+            <SelectFieldSync
+                label="Default Selected Item"
+                options={itemOptions}
+                value={selectedDefaultOption}
+                onSelectedOptionChange={handleDefaultChange}
+                filter={{ keys: ['label'] }}
+            />
+        </Flex>
+    );
+};

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

@@ -22,7 +22,7 @@ interface FieldConfigPanelOverlayProps {
     onFieldConfigChange(updates: Partial<PdfField>): void;
     onMatchingFieldsConfigChange?(
         predicate: (field: PdfField) => boolean,
-        updates: Partial<PdfField>,
+        updates: Partial<PdfField> | ((field: PdfField) => Partial<PdfField>),
     ): void;
     onDeleteField(): void;
     onDeselectField?(): void;

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

@@ -20,7 +20,9 @@ import {
     supportsFieldFontSize,
 } from '../../utils';
 import { DisplayCondition } from '../display-conditions/display-condition';
+import { DropdownFieldItems } from './dropdown-field-items';
 import { ESignOptionsModal } from './e-sign-options-modal';
+import { FillableDefaultConfig } from './fillable-default-config';
 import { FormulaGenerator } from './formula-generator';
 import { TableConfigs } from './table-configs';
 
@@ -37,7 +39,7 @@ interface FieldConfigPanelProps {
     onFieldConfigChange(updates: Partial<PdfField>): void;
     onMatchingFieldsConfigChange?(
         predicate: (field: PdfField) => boolean,
-        updates: Partial<PdfField>,
+        updates: Partial<PdfField> | ((field: PdfField) => Partial<PdfField>),
     ): void;
     onRequestFormFields(formId: number): void;
 }
@@ -228,6 +230,19 @@ export const FieldConfigPanel: FC<FieldConfigPanelProps> = ({
                     }
                 />
             )}
+            {field.type === FieldTypeEnum.fillable && field.subType === 'dropdown' && (
+                <DropdownFieldItems field={field} onFieldConfigChange={onFieldConfigChange} />
+            )}
+            {field.type === FieldTypeEnum.fillable &&
+                field.subType &&
+                ['text', 'number', 'checkbox', 'date', 'radio'].includes(field.subType) && (
+                    <FillableDefaultConfig
+                        field={field}
+                        documentFields={documentFields}
+                        onFieldConfigChange={onFieldConfigChange}
+                        onMatchingFieldsConfigChange={onMatchingFieldsConfigChange}
+                    />
+                )}
             {field.type === FieldTypeEnum.calculated && (
                 <FormulaGenerator
                     dataModel={dataModel}

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

@@ -0,0 +1,155 @@
+import {
+    Checkbox,
+    DateFieldSingle,
+    Flex,
+    NumberField,
+    SelectFieldSync,
+    TextField,
+} from '@servicetitan/anvil2';
+import { FC } from 'react';
+import { type PdfField } from '../../interface/types';
+
+interface FillableDefaultConfigProps {
+    field: PdfField;
+    documentFields?: PdfField[];
+    onFieldConfigChange(updates: Partial<PdfField>): void;
+    onMatchingFieldsConfigChange?(
+        predicate: (field: PdfField) => boolean,
+        updates: Partial<PdfField> | ((field: PdfField) => Partial<PdfField>),
+    ): void;
+}
+
+/**
+ * Configures `field.default` (DTE-4668) - an optional author-configured starting value that the
+ * fillable views merge in for display only when the recipient hasn't stored a value at this
+ * field's path yet. Mirrors the backend's `FillableDefault`/`ValidateDefault` shape and
+ * constraints one-for-one (`ByodField.cs`) so a template saved here never fails backend
+ * validation: a blank/whitespace text default is never authored (it's just "no default", same as
+ * omitting it), and a radio group can never end up with more than one option flagged as default.
+ */
+export const FillableDefaultConfig: FC<FillableDefaultConfigProps> = ({
+    documentFields = [],
+    field,
+    onFieldConfigChange,
+    onMatchingFieldsConfigChange,
+}) => {
+    const isRadioGroupSibling = (documentField: PdfField) =>
+        documentField.subType === 'radio' && documentField.path === field.path;
+
+    const radioGroupSiblings = documentFields.filter(isRadioGroupSibling);
+    const radioGroupOptions = radioGroupSiblings.map(sibling => ({
+        id: sibling.id,
+        label: sibling.label || sibling.id,
+    }));
+    const selectedRadioDefault =
+        radioGroupOptions.find(
+            option =>
+                radioGroupSiblings.find(sibling => sibling.id === option.id)?.default?.type ===
+                'radio',
+        ) ?? null;
+
+    switch (field.subType) {
+        case 'text':
+            return (
+                <TextField
+                    label="Default Value"
+                    value={field.default?.type === 'text' ? field.default.value : ''}
+                    onChange={e => {
+                        const value = e.target.value;
+                        onFieldConfigChange({
+                            default: value.trim() ? { type: 'text', value } : undefined,
+                        });
+                    }}
+                />
+            );
+
+        case 'number':
+            return (
+                <NumberField
+                    label="Default Value"
+                    value={field.default?.type === 'number' ? field.default.value : null}
+                    onChange={value =>
+                        onFieldConfigChange({
+                            default: value === null ? undefined : { type: 'number', value },
+                        })
+                    }
+                />
+            );
+
+        case 'checkbox':
+            return (
+                <Checkbox
+                    label="Checked by default"
+                    checked={field.default?.type === 'checkbox' ? field.default.value : false}
+                    onChange={() =>
+                        onFieldConfigChange({
+                            default:
+                                field.default?.type === 'checkbox'
+                                    ? undefined
+                                    : { type: 'checkbox', value: true },
+                        })
+                    }
+                />
+            );
+
+        case 'date':
+            return (
+                <Flex direction="column" gap="2">
+                    <Checkbox
+                        label="Default to today"
+                        checked={field.default?.type === 'today'}
+                        onChange={() =>
+                            onFieldConfigChange({
+                                default:
+                                    field.default?.type === 'today' ? undefined : { type: 'today' },
+                            })
+                        }
+                    />
+                    {field.default?.type !== 'today' && (
+                        <DateFieldSingle
+                            label="Default Value"
+                            value={field.default?.type === 'date' ? field.default.value : null}
+                            onChange={({ date }) =>
+                                onFieldConfigChange({
+                                    default: date ? { type: 'date', value: date } : undefined,
+                                })
+                            }
+                        />
+                    )}
+                </Flex>
+            );
+
+        case 'radio':
+            return (
+                <SelectFieldSync
+                    label="Default Selected Option"
+                    options={radioGroupOptions}
+                    value={selectedRadioDefault}
+                    onSelectedOptionChange={option => {
+                        if (field.path && onMatchingFieldsConfigChange) {
+                            /*
+                             * One update, matched against every option in the group, so the "only
+                             * one default per radio group" constraint is applied atomically - a
+                             * separate call per option would each compute its next-fields array
+                             * from the same stale `fields` snapshot and clobber the others instead
+                             * of composing.
+                             */
+                            onMatchingFieldsConfigChange(isRadioGroupSibling, siblingField => ({
+                                default:
+                                    siblingField.id === option?.id ? { type: 'radio' } : undefined,
+                            }));
+                            return;
+                        }
+
+                        onFieldConfigChange({
+                            default: option?.id === field.id ? { type: 'radio' } : undefined,
+                        });
+                    }}
+                    filter={{ keys: ['label'] }}
+                />
+            );
+
+        default:
+            return null;
+    }
+};

package/src/components/field-sidebar/calculated-field-type-list.tsx

@@ -18,6 +18,7 @@ export const CalculatedFieldTypeList: FC<CalculatedFieldTypeListProps> = ({
                 return (
                     <FieldType
                         key={key}
+                        icon={fieldOption.icon}
                         label={fieldOption.label}
                         onDragEnd={onDragEnd}
                         onDragStart={() => onDragStart(fieldOption)}

package/src/components/field-sidebar/e-sign-field-type-list.tsx

@@ -13,6 +13,7 @@ export const ESignFieldTypeList: FC<ESignFieldTypeListProps> = ({ onDragEnd, onD
         <div className="dte-field-type-items-wrapper">
             {E_SIGN_FIELD_TYPES.map(fieldOption => (
                 <FieldType
+                    icon={fieldOption.icon}
                     key={fieldOption.subType}
                     label={fieldOption.label}
                     onDragEnd={onDragEnd}

package/src/components/field-sidebar/field-type.tsx

@@ -1,15 +1,22 @@
-import { Flex, Icon, Text } from '@servicetitan/anvil2';
+import { Flex, Icon, Svg, Text } from '@servicetitan/anvil2';
 import IconDragIndicator from '@servicetitan/anvil2/assets/icons/material/round/drag_indicator.svg';
 import { FC } from 'react';
 
 interface FieldTypeProps {
+    icon?: Svg;
     label: string;
     sampleData?: string | number | null;
     onDragEnd(): void;
     onDragStart(): void;
 }
 
-export const FieldType: FC<FieldTypeProps> = ({ label, onDragEnd, onDragStart, sampleData }) => {
+export const FieldType: FC<FieldTypeProps> = ({
+    icon,
+    label,
+    onDragEnd,
+    onDragStart,
+    sampleData,
+}) => {
     return (
         <div
             draggable
@@ -24,7 +31,10 @@ export const FieldType: FC<FieldTypeProps> = ({ label, onDragEnd, onDragStart, s
         >
             <Icon svg={IconDragIndicator} size="medium" />
             <Flex direction="column" style={{ overflow: 'hidden' }}>
-                <Text size="small">{label}</Text>
+                <Flex alignItems="center" gap="2">
+                    {icon && <Icon svg={icon} size="medium" />}
+                    <Text size="small">{label}</Text>
+                </Flex>
                 {sampleData && (
                     <Text
                         size="small"

package/src/components/field-sidebar/fillable-field-type-list.tsx

@@ -37,6 +37,7 @@ export const FillableFieldTypeList: FC<FillableFieldTypeListProps> = ({
             {searchedFieldTypes.map(fieldOption => {
                 return (
                     <FieldType
+                        icon={fieldOption.icon}
                         key={fieldOption.subType}
                         label={fieldOption.label}
                         onDragEnd={onDragEnd}

package/src/components/field-sidebar/generic-field-type-list.tsx

@@ -16,6 +16,7 @@ export const GenericFieldTypeList: FC<GenericFieldTypeListProps> = ({ onDragEnd,
                 return (
                     <FieldType
                         key={key}
+                        icon={fieldOption.icon}
                         label={fieldOption.label}
                         onDragEnd={onDragEnd}
                         onDragStart={() => onDragStart(fieldOption)}