@servicetitan/dte-pdf-editor 1.42.0 → 1.43.0

package/src/components/field-sidebar/form-fields-type-list.tsx

@@ -0,0 +1,113 @@
+import { Button, Flex, Text } from '@servicetitan/anvil2';
+import IconArrowBack from '@servicetitan/anvil2/assets/icons/material/round/keyboard_arrow_left.svg';
+import IconArrowForward from '@servicetitan/anvil2/assets/icons/material/round/keyboard_arrow_right.svg';
+import { Stack } from '@servicetitan/design-system';
+import { FC, Fragment } from 'react';
+import { FieldTypeOption, FormInfo } from '../../interface/types';
+import { FieldType } from './field-type';
+
+export interface FormFieldsTypeListProps {
+    forms: FormInfo[];
+    selectedForm: FormInfo | null;
+    fieldOptions: FieldTypeOption[];
+    isLoadingFormFields?: boolean;
+    onSelectForm(form: FormInfo | null): void;
+    onDragEnd(): void;
+    onDragStart(fieldOption: FieldTypeOption): void;
+}
+
+export const FormFieldsTypeList: FC<FormFieldsTypeListProps> = ({
+    fieldOptions,
+    forms,
+    isLoadingFormFields = false,
+    onDragEnd,
+    onDragStart,
+    onSelectForm,
+    selectedForm,
+}) => {
+    return (
+        <Flex direction="column" gap={3} flex={1} style={{ minHeight: 0 }}>
+            <div className="dte-formula-sidebar-slide-outer">
+                <div
+                    className={`dte-formula-sidebar-slide-track${selectedForm ? ' --detail' : ''}`}
+                >
+                    <div className="dte-formula-sidebar-slide-panel">
+                        {forms.length > 0 ? (
+                            <ul
+                                className="dte-formula-field-list"
+                                role="listbox"
+                                aria-label="Forms"
+                            >
+                                {forms.map(form => (
+                                    <li
+                                        key={form.id}
+                                        role="option"
+                                        className="dte-formula-field-list-item"
+                                        onMouseDown={e => {
+                                            e.preventDefault();
+                                            onSelectForm(form);
+                                        }}
+                                    >
+                                        <Stack justifyContent="space-between" alignItems="center">
+                                            <span className="dte-text-ellipsis" title={form.name}>
+                                                {form.name}
+                                            </span>
+                                            <IconArrowForward />
+                                        </Stack>
+                                    </li>
+                                ))}
+                            </ul>
+                        ) : (
+                            <Text size="small" subdued variant="body">
+                                No forms configured.
+                            </Text>
+                        )}
+                    </div>
+
+                    <div className="dte-formula-sidebar-slide-panel --form-fields">
+                        {selectedForm ? (
+                            <Fragment>
+                                <Button
+                                    style={{ width: '100%' }}
+                                    appearance="ghost"
+                                    size="small"
+                                    icon={IconArrowBack}
+                                    title={selectedForm.name}
+                                    onClick={() => onSelectForm(null)}
+                                >
+                                    <Text
+                                        size="medium"
+                                        className="dte-text-ellipsis"
+                                        style={{ fontWeight: 'bold', width: '100%' }}
+                                    >
+                                        {selectedForm.name}
+                                    </Text>
+                                </Button>
+                                <div className="dte-field-type-group">
+                                    {isLoadingFormFields ? (
+                                        <Text size="small" subdued variant="body">
+                                            Loading fields…
+                                        </Text>
+                                    ) : fieldOptions.length === 0 ? (
+                                        <Text size="small" subdued variant="body">
+                                            No fields on this form.
+                                        </Text>
+                                    ) : (
+                                        fieldOptions.map(option => (
+                                            <FieldType
+                                                key={option.path}
+                                                label={option.label}
+                                                onDragEnd={onDragEnd}
+                                                onDragStart={() => onDragStart(option)}
+                                            />
+                                        ))
+                                    )}
+                                </div>
+                            </Fragment>
+                        ) : null}
+                    </div>
+                </div>
+            </div>
+        </Flex>
+    );
+};

package/src/components/pdf-editor/pdf-editor.tsx

@@ -1,7 +1,14 @@
 import { Flex } from '@servicetitan/anvil2';
 import { FC, ReactNode, useCallback, useMemo, useRef } from 'react';
-import { usePdfFieldDnD, usePdfFieldSelection } from '../../hooks';
-import { FieldTypeEnum, PdfField, RecipientInfo, SchemaObject } from '../../interface/types';
+import { useFormFields, usePdfFieldDnD, usePdfFieldSelection } from '../../hooks';
+import {
+    FieldTypeEnum,
+    FormFieldsByFormIdI,
+    FormInfo,
+    PdfField,
+    RecipientInfo,
+    SchemaObject,
+} from '../../interface/types';
 import { extractGroupedFieldsFromDataModel, mapColorsToRecipients } from '../../utils';
 import { FieldConfigPanelOverlay } from '../field-config-panel/field-config-panel-overlay';
 import { FieldSidebar } from '../field-sidebar/field-sidebar';
@@ -20,6 +27,11 @@ export interface PdfEditorProps {
     fields?: PdfField[];
     hideFields?: FieldTypeEnum[];
     hideConditionalLogic?: boolean;
+    forms?: FormInfo[];
+    onFormSelect?: (
+        formIds: number[],
+        sendFormFields: (formFieldsByFormId: FormFieldsByFormIdI) => void,
+    ) => void;
     onLoadSuccess?(numPages: number): void;
     onFieldsChange(fields: PdfField[]): void;
 }
@@ -29,34 +41,27 @@ export const PdfEditor: FC<PdfEditorProps> = ({
     errorPlaceholder,
     errors = {},
     fields = [],
+    forms,
     hideConditionalLogic,
     hideFields,
     loading = false,
     loadingPlaceholder,
     onFieldsChange,
+    onFormSelect,
     onLoadSuccess,
     pdfUrl,
     recipients = [],
 }) => {
     const pdfContainerRef = useRef<HTMLDivElement>(null);
     const pdfWrapperRef = useRef<HTMLDivElement>(null);
-    const {
-        deleteSelectedField,
-        deselectField,
-        moveField,
-        resizeField,
-        selectField,
-        selectedField,
-        setSelectedFieldId,
-        updateField,
-    } = usePdfFieldSelection(fields, onFieldsChange);
-
+    const pdfFieldSelection = usePdfFieldSelection(fields, onFieldsChange);
+    const formFields = useFormFields(fields, onFormSelect);
     const pdfFieldDnd = usePdfFieldDnD({
         fields,
         recipients,
         onFieldsChange,
         pdfWrapperRef,
-        onSelectField: setSelectedFieldId,
+        onSelectField: pdfFieldSelection.setSelectedFieldId,
     });
 
     const dataModelGroups = useMemo(
@@ -73,16 +78,20 @@ export const PdfEditor: FC<PdfEditorProps> = ({
 
     return (
         <Flex flex={1} className={`dte-pdf-editor ${loading ? 'skeleton' : ''}`}>
-            {selectedField && (
+            {pdfFieldSelection.selectedField && (
                 <FieldConfigPanelOverlay
                     dataModel={dataModel}
                     documentFields={fields}
-                    selectedField={selectedField}
-                    onFieldConfigChange={updateField}
-                    onDeleteField={deleteSelectedField}
+                    formFieldsByFormId={formFields.formFieldsByFormId}
+                    forms={forms ?? []}
+                    formulaLoadingFormId={formFields.formulaLoadingFormId}
+                    selectedField={pdfFieldSelection.selectedField}
+                    onFieldConfigChange={pdfFieldSelection.updateField}
+                    onDeleteField={pdfFieldSelection.deleteSelectedField}
                     recipients={recipients}
-                    onDeselectField={deselectField}
+                    onDeselectField={pdfFieldSelection.deselectField}
                     hideConditionalLogic={hideConditionalLogic}
+                    onRequestFormFields={formFields.requestFormFieldsById}
                 />
             )}
 
@@ -90,8 +99,13 @@ export const PdfEditor: FC<PdfEditorProps> = ({
                 <FieldSidebar
                     hideFields={hideFields}
                     dataModelGroups={dataModelGroups}
+                    formFieldOptions={formFields.formFieldOptions}
+                    forms={forms}
+                    isLoadingFormFields={formFields.isLoading}
                     onDragStart={pdfFieldDnd.handleDragStart}
                     onDragEnd={pdfFieldDnd.handleDragEnd}
+                    onSelectForm={formFields.handleSelectForm}
+                    selectedForm={formFields.selectedForm}
                 />
             </Flex>
 
@@ -103,7 +117,7 @@ export const PdfEditor: FC<PdfEditorProps> = ({
                     errors={errors}
                     onLoadSuccess={onLoadSuccess}
                     recipientsColors={recipientsColors}
-                    selectedField={selectedField}
+                    selectedField={pdfFieldSelection.selectedField}
                     pdfContainerRef={pdfContainerRef}
                     pdfWrapperRef={pdfWrapperRef}
                     errorPlaceholder={errorPlaceholder}
@@ -111,11 +125,11 @@ export const PdfEditor: FC<PdfEditorProps> = ({
                     handleAddNewField={handleAddNewField}
                     onDrop={pdfFieldDnd.handleDrop}
                     onDragOver={pdfFieldDnd.handleDragOver}
-                    onFieldClick={selectField}
-                    onFieldMove={moveField}
-                    onFieldResize={resizeField}
-                    onDeselectField={deselectField}
-                    onFieldConfigChange={updateField}
+                    onFieldClick={pdfFieldSelection.selectField}
+                    onFieldMove={pdfFieldSelection.moveField}
+                    onFieldResize={pdfFieldSelection.resizeField}
+                    onDeselectField={pdfFieldSelection.deselectField}
+                    onFieldConfigChange={pdfFieldSelection.updateField}
                 />
             </Flex>
         </Flex>

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

@@ -77,7 +77,9 @@ export const PdfOverlayField: FC<PdfOverlayFieldProps> = ({
         >
             {field.type === FieldTypeEnum.calculated && <PdfOverlayFieldCalculated field={field} />}
             {field.type === FieldTypeEnum.eSign && <PdfOverlayFieldESign field={field} />}
-            {field.type === FieldTypeEnum.dataModel && <PdfOverlayFieldDataModel field={field} />}
+            {(field.type === FieldTypeEnum.dataModel || field.type === FieldTypeEnum.forms) && (
+                <PdfOverlayFieldDataModel field={field} />
+            )}
             {field.type === FieldTypeEnum.fillable && (
                 <PdfOverlayFieldFillable field={field} handleAddNewField={handleAddNewField} />
             )}

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

@@ -103,7 +103,8 @@ export const PdfView: FC<PdfViewProps> = ({
                                 recipientsColors={recipientsColors}
                                 pdfWrapperRef={pdfWrapperRef}
                             >
-                                {field.type === FieldTypeEnum.dataModel && (
+                                {(field.type === FieldTypeEnum.dataModel ||
+                                    field.type === FieldTypeEnum.forms) && (
                                     <PdfViewDataModel field={field} data={data} />
                                 )}
                                 {field.type === FieldTypeEnum.eSign && (

package/src/constants/menu-group.ts

@@ -1,5 +1,6 @@
 import IconBorderColor from '@servicetitan/anvil2/assets/icons/material/round/border_color.svg';
 import IconCalculate from '@servicetitan/anvil2/assets/icons/material/round/calculate.svg';
+import IconFactCheck from '@servicetitan/anvil2/assets/icons/material/round/fact_check.svg';
 import IconPhotoSizeSelectSmall from '@servicetitan/anvil2/assets/icons/material/round/photo_size_select_small.svg';
 import IconCommercial from '@servicetitan/anvil2/assets/icons/st/commercial.svg';
 import IconEstimate from '@servicetitan/anvil2/assets/icons/st/estimate.svg';
@@ -29,4 +30,5 @@ export const menuGroups: MenuGroupModel[] = [
         label: 'Generic Fields',
         key: FieldTypeEnum.generic,
     },
+    { svgIcon: IconFactCheck, label: 'Forms', key: FieldTypeEnum.forms },
 ];

package/src/hooks/index.ts

@@ -1,5 +1,6 @@
 export * from './useFieldDrag';
 export * from './useFieldResize';
+export * from './useFormFields';
 export * from './useFormulaEditor';
 export * from './usePdfDocumentRenderer';
 export * from './usePdfFieldDnD';

package/src/hooks/useFormFields.ts

@@ -0,0 +1,157 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+    FieldTypeEnum,
+    FieldTypeOption,
+    FormFieldsByFormIdI,
+    FormInfo,
+    PdfField,
+} from '../interface/types';
+import { formFieldInfoToFieldTypeOption } from '../utils';
+
+interface UseFormFieldsResult {
+    isLoading: boolean;
+    formFieldsByFormId: FormFieldsByFormIdI;
+    formulaLoadingFormId: null | number;
+    formFieldOptions: FieldTypeOption[];
+    selectedForm: FormInfo | null;
+    handleSelectForm: (form: FormInfo | null) => void;
+    requestFormFieldsById: (formId: number) => void;
+}
+
+export const useFormFields = (
+    fields: PdfField[],
+    onFormSelect?: (
+        formIds: number[],
+        sendFormFields: (formFieldsByFormId: FormFieldsByFormIdI) => void,
+    ) => void,
+): UseFormFieldsResult => {
+    const [formFieldsByFormId, setFormFieldsByFormId] = useState<FormFieldsByFormIdI>({});
+    const [formulaLoadingFormId, setFormulaLoadingFormId] = useState<number | null>(null);
+    const [selectedForm, setSelectedForm] = useState<FormInfo | null>(null);
+    const [formFieldsLoadingFormIds, setFormFieldsLoadingFormIds] = useState<Record<number, true>>(
+        {},
+    );
+
+    const formFieldsByFormIdRef = useRef(formFieldsByFormId);
+    formFieldsByFormIdRef.current = formFieldsByFormId;
+
+    useEffect(() => {
+        if (!onFormSelect) {
+            return;
+        }
+
+        const initialFormIds = new Set<number>();
+        fields.forEach(field => {
+            if (field.type === FieldTypeEnum.calculated) {
+                if (field?.formula?.tokens.length) {
+                    field.formula.tokens.forEach(token => {
+                        if (token.type === 'field' && token.formSnapshot) {
+                            initialFormIds.add(token.formSnapshot.formId);
+                        }
+                    });
+                }
+            }
+        });
+
+        if (!initialFormIds.size) {
+            return;
+        }
+
+        let cancelled = false;
+        const rafId = requestAnimationFrame(() => {
+            if (cancelled) {
+                return;
+            }
+            const cache = formFieldsByFormIdRef.current;
+            const missingFormIds = [...initialFormIds].filter(formId => !cache[formId]);
+            if (!missingFormIds.length) {
+                return;
+            }
+            setFormFieldsLoadingFormIds(prev => ({
+                ...prev,
+                ...Object.fromEntries(missingFormIds.map(id => [id, true])),
+            }));
+            onFormSelect(missingFormIds, receivedByFormId => {
+                if (cancelled) {
+                    return;
+                }
+                setFormFieldsByFormId(prev => ({ ...prev, ...receivedByFormId }));
+                setFormFieldsLoadingFormIds(prev => {
+                    const next = { ...prev };
+                    for (const id of Object.keys(receivedByFormId)) {
+                        delete next[Number(id)];
+                    }
+                    return next;
+                });
+            });
+        });
+
+        return () => {
+            cancelled = true;
+            cancelAnimationFrame(rafId);
+        };
+    }, [fields, onFormSelect]);
+
+    const formFieldOptions = useMemo(() => {
+        if (!selectedForm) {
+            return [];
+        }
+        const list = formFieldsByFormId[selectedForm.id];
+        if (!list?.length) {
+            return [];
+        }
+        return list.map(f => formFieldInfoToFieldTypeOption(selectedForm.id, f, selectedForm.name));
+    }, [formFieldsByFormId, selectedForm]);
+
+    const handleSelectForm = useCallback(
+        (form: FormInfo | null) => {
+            setSelectedForm(form);
+            if (form) {
+                if (!formFieldsByFormId[form.id]?.length && onFormSelect) {
+                    setFormFieldsLoadingFormIds({ [form.id]: true });
+                    onFormSelect([form.id], loadedByFormId => {
+                        setFormFieldsByFormId(prev => ({ ...prev, ...loadedByFormId }));
+                        setFormFieldsLoadingFormIds(prev => {
+                            const next = { ...prev };
+                            for (const id of Object.keys(loadedByFormId)) {
+                                delete next[Number(id)];
+                            }
+                            return next;
+                        });
+                    });
+                } else {
+                    setFormFieldsLoadingFormIds({});
+                }
+            } else {
+                setFormFieldsLoadingFormIds({});
+            }
+        },
+        [onFormSelect, formFieldsByFormId],
+    );
+
+    const requestFormFieldsById = useCallback(
+        (formId: number) => {
+            if (!onFormSelect || formFieldsByFormId[formId]?.length) {
+                return;
+            }
+            setFormulaLoadingFormId(formId);
+            onFormSelect([formId], loadedByFormId => {
+                setFormFieldsByFormId(prev => ({ ...prev, ...loadedByFormId }));
+                setFormulaLoadingFormId(null);
+            });
+        },
+        [formFieldsByFormId, onFormSelect],
+    );
+
+    const isLoading = selectedForm != null && formFieldsLoadingFormIds[selectedForm.id];
+
+    return {
+        isLoading,
+        formFieldsByFormId,
+        formulaLoadingFormId,
+        formFieldOptions,
+        selectedForm,
+        handleSelectForm,
+        requestFormFieldsById,
+    };
+};

package/src/hooks/useFormulaEditor.ts

@@ -35,6 +35,11 @@ export const useFormulaEditor = (params: {
     const historyRef = useRef<string[]>([currentExpression]);
     const knownDateFieldsRef = useRef(knownDateFields);
 
+    /*
+     * Reset draft only when the modal opens or the saved formula from props changes.
+     * Do not depend on pathToLabel: merge-tag / form labels load async and a new Map
+     * reference would wipe in-progress edits (e.g. clear formula → pick a field).
+     */
     useEffect(() => {
         if (opened) {
             setDraftExpression(currentExpression);
@@ -49,7 +54,8 @@ export const useFormulaEditor = (params: {
                 placeCaretAtEnd(editor);
             }
         }
-    }, [opened, currentExpression, pathToLabel]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- pathToLabel updates re-render via the draftExpression effect
+    }, [opened, currentExpression]);
 
     useEffect(() => {
         const editor = editorRef.current;

package/src/hooks/usePdfFieldDnD.ts

@@ -52,6 +52,10 @@ const initializeDroppedFieldByType: Record<FieldTypeEnum, InitializeDroppedField
         path: base.id,
     }),
     [FieldTypeEnum.dataModel]: base => base,
+    [FieldTypeEnum.forms]: (base, option) => ({
+        ...base,
+        ...(option.formSnapshot ? { formSnapshot: option.formSnapshot } : {}),
+    }),
     [FieldTypeEnum.generic]: base => {
         const defaultSize = GENERIC_FIELD_DEFAULT_SIZES[base.subType!];
         if (base.subType === 'text') {

package/src/interface/types.ts

@@ -1,5 +1,6 @@
 export enum FieldTypeEnum {
     dataModel = 'dataModel',
+    forms = 'forms',
     eSign = 'eSign',
     fillable = 'fillable',
     calculated = 'calculated',
@@ -16,8 +17,23 @@ export enum ESignFieldType {
 export type FillableFieldType = 'text' | 'date' | 'checkbox' | 'radio' | 'number';
 
 export type GenericFieldType = 'table' | 'text';
+export type FormFieldType = 'number' | 'text' | 'date';
 
-export type PdfFieldSubType = FillableFieldType | ESignFieldType | GenericFieldType;
+export interface FormFieldsByFormIdI {
+    [formId: number]: FormFieldInfo[];
+}
+
+export interface FormFieldInfo {
+    id: string;
+    header: string;
+    itemType: FormFieldType;
+}
+
+export interface FormInfo {
+    id: number;
+    name: string;
+}
+export type PdfFieldSubType = FillableFieldType | ESignFieldType | GenericFieldType | FormFieldType;
 
 export interface GenericFieldTableDataType {
     showHeader: boolean;
@@ -54,10 +70,11 @@ export interface DisplayConditionGroup {
 
 export interface DisplayConditionSingle {
     id: string;
+    value: string;
+    operator: string;
     dataPointKey: string;
     logicalOperator?: 'and' | 'or';
-    operator: string;
-    value: string;
+    formSnapshot?: FormulaFieldFormSnapshot;
 }
 
 export interface PdfField {
@@ -72,6 +89,7 @@ export interface PdfField {
     height: number;
     required?: boolean;
     path?: string;
+    formSnapshot?: FormulaFieldFormSnapshot;
     recipient?: string;
     description?: string;
     data?: FieldDataType;
@@ -88,6 +106,7 @@ export interface FieldTypeOption {
     subType?: PdfFieldSubType;
     path?: string;
     fieldType?: SchemaFieldType;
+    formSnapshot?: FormulaFieldFormSnapshot;
 }
 
 export interface DataModelFieldGroup {
@@ -99,13 +118,32 @@ export interface DataModelFieldGroup {
 export const FORMULA_OPERATORS = ['+', '-', '*', '/'];
 export type FormulaOperator = (typeof FORMULA_OPERATORS)[number];
 
+/**
+ * Snapshot metadata for a bound form submission field (`__submission_fields.*` path):
+ * used on `PdfField` with `type: forms`, on `FieldTypeOption` for drag payloads, on
+ * structured-formula `field` tokens, and on `DisplayConditionSingle` when the condition uses a
+ * form field.
+ */
+export interface FormulaFieldFormSnapshot {
+    formId: number;
+    fieldId: string;
+    formName: string;
+    fieldName: string;
+    fieldType: FormFieldType;
+}
+
 /** Single token in a structured formula (number, operator, paren, or field reference) */
 export type FormulaToken =
     | { type: 'number'; value: string }
     | { type: 'operator'; value: FormulaOperator }
     | { type: 'lparen' }
     | { type: 'rparen' }
-    | { type: 'field'; path: string; fieldType: SchemaFieldType };
+    | {
+          type: 'field';
+          path: string;
+          fieldType: SchemaFieldType;
+          formSnapshot?: FormulaFieldFormSnapshot;
+      };
 
 /** Structured formula representation (AST-like token list) for validation and safe editing */
 export interface StructuredFormula {
@@ -241,4 +279,5 @@ export interface DataPointOption {
     fieldType: 'number' | 'string';
     fullKey: string;
     title: string;
+    formSnapshot?: FormulaFieldFormSnapshot;
 }

package/src/styles/field-type-list.css

@@ -1,5 +1,6 @@
 .dte-field-type-group {
     margin-top: var(--spacing-1);
+    padding-left: 1px;
 }
 
 .dte-field-type-group-header {